eslint-plugin-etc-misc 1.0.1

package/docs/rules/typescript-require-this-void.md

@@ -0,0 +1,95 @@
+# typescript/require-this-void
+
+Require `this: void` on static class methods.
+
+## Targeted pattern scope
+
+This rule targets static class methods whose function expression parameters do
+not start with `this: void`.
+
+## What this rule reports
+
+This rule reports static class methods that do not declare a `this: void` parameter.
+
+## Why this rule exists
+
+An explicit `this: void` parameter documents that static methods do not depend
+on a `this` context.
+
+## ❌ Incorrect
+
+```ts
+class C {
+    static f() {}
+}
+```
+
+## ✅ Correct
+
+```ts
+class C {
+    static f(this: void) {}
+}
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Migration is adding `this: void` as the first static method parameter.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+class C {
+    static parse(this: C, value: string): C {
+        return new C();
+    }
+}
+// ❌ reported: first parameter is not `this: void`
+
+class D {
+    static parse(this: void, value: string): D {
+        return new D();
+    }
+}
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/require-this-void": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project does not enforce explicit static-method `this` typing.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R130
+
+## Further reading
+
+- [TypeScript: this parameters](https://www.typescriptlang.org/docs/handbook/2/functions.html#declaring-this-in-a-function)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.

package/docs/rules/underscore-internal.md

@@ -0,0 +1,112 @@
+# underscore-internal
+
+Disallow `@internal` APIs that are not underscore-prefixed.
+
+## Targeted pattern scope
+
+This rule checks identifier names for declarations/signatures such as:
+
+- class/function/type/interface/enum declarations,
+- variable declarators,
+- class methods/properties,
+- interface method/property signatures,
+- enum members.
+
+It reports names that do not start with `_` when `@internal` is present in a
+leading comment for the node (or its export declaration wrapper).
+
+## What this rule reports
+
+This rule reports declarations tagged with `@internal` when their names do not begin with `_`.
+
+The convention makes internal-only APIs visually obvious and helps prevent accidental public use.
+
+## Why this rule exists
+
+It enforces a consistent signal that internal-only APIs are not part of the
+public contract.
+
+## ❌ Incorrect
+
+```ts
+/** @internal */
+export function parseSecret(): void {}
+```
+
+```ts
+export interface Thing {
+    /** @internal */
+    compute(): number;
+}
+```
+
+## ✅ Correct
+
+```ts
+/** @internal */
+export function _parseSecret(): void {}
+```
+
+```ts
+export interface Thing {
+    /** @internal */
+    _compute(): number;
+}
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Migration is typically renaming internal declarations to use an underscore
+prefix.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+/** @internal */
+export const token = "x";
+// ❌ reported
+
+/** @internal */
+export const _token = "x";
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/underscore-internal": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project uses a different naming convention for internal APIs.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R076
+
+## Further reading
+
+- [TSDoc `@internal` tag](https://tsdoc.org/pages/tags/internal/)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.

package/docs/rules/unused-internal-properties.md

@@ -0,0 +1,100 @@
+# unused-internal-properties
+
+Disallow object properties that are defined but never read.
+
+## Targeted pattern scope
+
+This rule targets object literal properties.
+
+## What this rule reports
+
+This rule reports properties that are declared but never consumed.
+
+## Why this rule exists
+
+Dead properties make object shapes noisy and increase long-term maintenance
+cost.
+
+## ❌ Incorrect
+
+```ts
+const data = {
+    used: 1,
+    unused: 2,
+};
+
+console.log(data.used);
+```
+
+## ✅ Correct
+
+```ts
+const data = {
+    used: 1,
+    alsoUsed: 2,
+};
+
+console.log(data.used + data.alsoUsed);
+```
+
+## Behavior and migration notes
+
+This rule forwards options and behavior to `unicorn/no-unused-properties`.
+
+- **Lifecycle:** Deprecated and frozen.
+- **Deprecated since:** `v1.0.0`
+- **Available until:** `v2.0.0`
+- **Use instead:** [`unicorn/no-unused-properties`](https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-unused-properties.md)
+
+## Additional examples
+
+```ts
+const result = {
+    id: 1,
+    debug: true,
+};
+console.log(result.id);
+// ❌ `debug` is never read
+
+const resultFixed = {
+    id: 1,
+    debug: true,
+};
+console.log(resultFixed.id, resultFixed.debug);
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/unused-internal-properties": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule when object literals intentionally include reserved fields for
+external contracts.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R077
+
+## Further reading
+
+- [unicorn: `no-unused-properties`](https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-unused-properties.md)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.

package/docs/rules/uppercase-iife.md

@@ -0,0 +1,82 @@
+# uppercase-iife
+
+Disallow unreadable immediately invoked arrow function expressions.
+
+## Targeted pattern scope
+
+This rule targets immediately invoked arrow function expressions (IIFEs).
+
+## What this rule reports
+
+This rule reports IIFEs whose arrow function body is an unnecessary
+parenthesized expression.
+
+## Why this rule exists
+
+Extra parentheses in IIFE arrow bodies reduce readability and add noise.
+
+## ❌ Incorrect
+
+```ts
+(() => (doWork()))();
+```
+
+## ✅ Correct
+
+```ts
+(() => doWork())();
+```
+
+## Behavior and migration notes
+
+This rule forwards options and behavior to `unicorn/no-unreadable-iife`.
+
+- **Lifecycle:** Deprecated and frozen.
+- **Deprecated since:** `v1.0.0`
+- **Available until:** `v2.0.0`
+- **Use instead:** [`unicorn/no-unreadable-iife`](https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-unreadable-iife.md)
+
+## Additional examples
+
+```ts
+const value = (() => (compute()))();
+// ❌ reported by forwarded unicorn rule
+
+const valueFixed = (() => compute())();
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/uppercase-iife": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team deliberately keeps this parenthesized IIFE style
+for historical consistency.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R078
+
+## Further reading
+
+- [unicorn: `no-unreadable-iife`](https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-unreadable-iife.md)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.

package/docs/rules/words.md

@@ -0,0 +1,83 @@
+# words
+
+Disallow vague or weak wording in comments.
+
+## Targeted pattern scope
+
+This rule targets source-code comments.
+
+## What this rule reports
+
+This rule reports weak, vague, or overly wordy phrasing in comments.
+
+## Why this rule exists
+
+Ambiguous comment language reduces maintainability and leaves intent unclear.
+
+## ❌ Incorrect
+
+```ts
+// this probably works
+const value = 1;
+```
+
+## ✅ Correct
+
+```ts
+// this works for positive integers
+const value = 1;
+```
+
+## Behavior and migration notes
+
+This rule forwards options and behavior to
+`write-good-comments/write-good-comments`.
+
+- **Lifecycle:** Deprecated and frozen.
+- **Deprecated since:** `v1.0.0`
+- **Available until:** `v2.0.0`
+- **Use instead:** [`write-good-comments/write-good-comments`](https://github.com/kantord/eslint-plugin-write-good-comments)
+
+## Additional examples
+
+```ts
+// It should probably maybe work for most inputs.
+// ❌ likely reported by write-good-comments checks
+
+// Handles positive integers and returns false for negative values.
+// ✅ clearer and more precise
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/words": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team does not want prose-quality checks for comments.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R079
+
+## Further reading
+
+- [eslint-plugin-write-good-comments](https://github.com/kantord/eslint-plugin-write-good-comments)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.