eslint-plugin-etc-misc 1.0.1

package/docs/rules/typescript-no-unsafe-object-assignment.md

@@ -0,0 +1,93 @@
+# typescript/no-unsafe-object-assignment
+
+Disallow assignments to targets with readonly properties.
+
+## Targeted pattern scope
+
+⚠️ This rule requires type information to run. Configure type-aware linting (`parserOptions.project` or `projectService`) before enabling it.
+
+This rule is a TypeScript-prefixed alias of
+`typescript/no-unsafe-object-assign`.
+
+It reports `Object.assign(...)` calls where the target type has readonly
+properties.
+
+## What this rule reports
+
+This rule reports `Object.assign` calls that attempt to mutate readonly-typed
+targets.
+
+## Why this rule exists
+
+Mutating readonly-shaped targets through `Object.assign` bypasses the intent of
+readonly contracts and can hide unsafe state changes.
+
+## ❌ Incorrect
+
+```ts
+type Target = { readonly x: number };
+const target: Target = { x: 1 };
+Object.assign(target, { x: 2 });
+```
+
+## ✅ Correct
+
+```ts
+type Target = { x: number };
+const target: Target = { x: 1 };
+Object.assign(target, { x: 2 });
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Use immutable update patterns or non-readonly target types when mutation is
+intentional.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+const readonlyTarget: Readonly<{ value: number }> = { value: 1 };
+Object.assign(readonlyTarget, { value: 2 });
+// ❌ reported
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/no-unsafe-object-assignment": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project intentionally permits mutating readonly-typed
+targets via `Object.assign`.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R102
+
+## Further reading
+
+- [TypeScript-ESLint: Typed Linting](https://typescript-eslint.io/getting-started/typed-linting)
+
+## 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/typescript-prefer-array-type-alias.md

@@ -0,0 +1,87 @@
+# typescript/prefer-array-type-alias
+
+Prefer reusable alias names for array and tuple type aliases.
+
+## Targeted pattern scope
+
+This rule targets type alias identifiers when the alias annotation is:
+
+- `TSArrayType` (`T[]`), or
+- `TSTupleType` (`[A, B]`).
+
+The alias name must match a PascalCase pattern ending in `Array` or `s`.
+
+## What this rule reports
+
+This rule reports array/tuple type aliases that do not follow preferred reusable alias naming.
+
+## Why this rule exists
+
+Collection-shaped aliases become easier to recognize and search when naming is
+consistent.
+
+## ❌ Incorrect
+
+```ts
+type Item = string[];
+```
+
+## ✅ Correct
+
+```ts
+type Items = string[];
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Migration is typically renaming the alias and updating references.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+type Pair = [string, string];
+// ❌ reported
+
+type Pairs = [string, string];
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/prefer-array-type-alias": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project does not standardize alias naming for array and tuple types.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R103
+
+## Further reading
+
+- [TypeScript: Tuple Types](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types)
+
+## 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/typescript-prefer-class-method.md

@@ -0,0 +1,87 @@
+# typescript/prefer-class-method
+
+Prefer class methods over untyped arrow-function class properties.
+
+## Targeted pattern scope
+
+This rule targets class property definitions whose value is an arrow function
+and whose property itself has no explicit type annotation.
+
+## What this rule reports
+
+This rule reports class property arrow functions that have no explicit property type annotation.
+
+## Why this rule exists
+
+Method syntax is often clearer for class behavior and avoids extra per-instance
+function property declarations.
+
+## ❌ Incorrect
+
+```ts
+class C {
+    value = () => {};
+}
+```
+
+## ✅ Correct
+
+```ts
+class C {
+    value(): void {}
+}
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+A typed function property (for example `x: () => void = () => {}`) is not
+reported by this rule.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+class C {
+    handler: () => void = () => {};
+}
+// ✅ valid (explicit property type annotation)
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/prefer-class-method": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if class-property arrow functions are your preferred pattern.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R104
+
+## Further reading
+
+- [TypeScript: Classes](https://www.typescriptlang.org/docs/handbook/2/classes.html)
+
+## 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/typescript-prefer-enum.md

@@ -0,0 +1,99 @@
+# typescript/prefer-enum
+
+Prefer enums over string literal comparisons and unions.
+
+## Targeted pattern scope
+
+⚠️ This rule requires type information to run. Configure type-aware linting (`parserOptions.project` or `projectService`) before enabling it.
+
+This rule reports three patterns:
+
+- string literal comparisons against enum-like expressions,
+- string literal `return` values from enum-like return contexts,
+- type aliases that are pure unions of multiple string literals.
+
+## What this rule reports
+
+This rule reports opportunities to replace string-literal-based state modeling
+with enum members.
+
+## Why this rule exists
+
+Enums centralize allowed values and reduce drift between string literals spread
+across comparisons, returns, and type unions.
+
+## ❌ Incorrect
+
+```ts
+type Status = "open" | "closed";
+// ❌ reported (pure string-literal union)
+```
+
+## ✅ Correct
+
+```ts
+enum Status {
+    Open = "open",
+    Closed = "closed",
+}
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Because it uses type analysis for enum-like checks, ensure parser services are
+enabled in lint configuration.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+enum Status {
+    Open = "open",
+    Closed = "closed",
+}
+
+const getStatus = (): Status => {
+    return "open";
+};
+// ❌ reported (string literal return in enum-like return context)
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/prefer-enum": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if string literal unions are preferred over enums in your
+project's type design.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R105
+
+## Further reading
+
+- [TypeScript-ESLint: Typed Linting](https://typescript-eslint.io/getting-started/typed-linting)
+
+## 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/typescript-prefer-named-tuple-members.md

@@ -0,0 +1,104 @@
+# typescript/prefer-named-tuple-members
+
+Prefer explicit names for tuple members in TypeScript tuple types.
+
+## Targeted pattern scope
+
+This rule targets tuple type members that are not named:
+
+- standard tuple members (for example `[string, number]`)
+- optional tuple members (for example `[string?]`)
+- rest tuple members (for example `[...string[]]`)
+
+It does not report tuples where all members are already named.
+
+## What this rule reports
+
+This rule reports tuple types that contain one or more unnamed members.
+
+## Why this rule exists
+
+Named tuple members improve readability and API clarity, especially when tuple
+positions have semantic meaning.
+
+## ❌ Incorrect
+
+```ts
+type RGB = [number, number, number];
+
+type Pair = [id: string, number?];
+
+type Params = [...string[]];
+```
+
+## ✅ Correct
+
+```ts
+type RGB = [red: number, green: number, blue: number];
+
+type Pair = [id: string, value?: number];
+
+type Params = [...rest: string[]];
+```
+
+## Behavior and migration notes
+
+This rule is autofixable and also provides suggestions.
+
+For unnamed members, the fixer generates deterministic placeholder names:
+
+- `item1`, `item2`, `item3`, ...
+- optional members become `itemN?: Type`
+- rest members become `...itemN: Type[]`
+
+You can keep the generated names or refine them to domain-specific names.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+type Point = [number, number];
+// ❌ reported
+
+type Point = [x: number, y: number];
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/prefer-named-tuple-members": "warn",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team intentionally prefers positional tuples without
+member names.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R106
+
+## Further reading
+
+- [TypeScript Handbook: Tuple Types](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types)
+- [TypeScript 4.0: Named Tuple Members](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#named-tuple-elements)
+
+## 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/typescript-prefer-readonly-array-parameter.md

@@ -0,0 +1,106 @@
+# typescript/prefer-readonly-array-parameter
+
+Require readonly array-like types for function and method parameters.
+
+## Targeted pattern scope
+
+This rule targets top-level array-like parameter type annotations, including:
+
+- `T[]`
+- tuple types (`[A, B]`)
+- `Array<T>`
+- union/intersection members such as `T[] | null`
+
+It also checks constructor parameter properties.
+
+## What this rule reports
+
+This rule reports parameter annotations that use mutable array-like types.
+
+## Why this rule exists
+
+Parameters are API boundaries. Marking array-like parameter types as readonly
+reduces accidental mutation and clarifies intent for callers and implementers.
+
+## ❌ Incorrect
+
+```ts
+function parse(values: string[]) {}
+
+const fn = (pair: [string, number]) => pair[0];
+
+class Store {
+    constructor(private keys: Array<string>) {}
+}
+```
+
+## ✅ Correct
+
+```ts
+function parse(values: readonly string[]) {}
+
+const fn = (pair: readonly [string, number]) => pair[0];
+
+class Store {
+    constructor(private keys: ReadonlyArray<string>) {}
+}
+```
+
+## Behavior and migration notes
+
+This rule is autofixable and also provides suggestions.
+
+- `Array<T>` is converted to `ReadonlyArray<T>`.
+- `T[]` and tuple types are converted to `readonly ...` forms.
+
+The rule intentionally checks only top-level parameter types (and top-level
+union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+function f(values: string[] | null): void {}
+// ❌ reported
+
+function f(values: readonly string[] | null): void {}
+// ✅ valid
+
+function f(config: { values: string[] }): void {}
+// ✅ valid (nested property type is out of scope)
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/prefer-readonly-array-parameter": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally mutates array-like parameter
+values and you do not want readonly parameter contracts.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R108
+
+## Further reading
+
+- [TypeScript: ReadonlyArray<T>](https://www.typescriptlang.org/docs/handbook/interfaces.html#readonly-properties)
+- [TypeScript: Tuple Types](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types)
+
+## 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/typescript-prefer-readonly-array.md

@@ -0,0 +1,86 @@
+# typescript/prefer-readonly-array
+
+Require readonly array and tuple type annotations.
+
+## Targeted pattern scope
+
+This rule targets mutable array-like annotations, including:
+
+- `T[]` and tuple annotations not wrapped in `readonly ...`, and
+- `Array<T>` references.
+
+## What this rule reports
+
+This rule reports writable array and tuple type annotations.
+
+## Why this rule exists
+
+Readonly array/tuple annotations communicate immutability at API boundaries and
+reduce accidental mutation.
+
+## ❌ Incorrect
+
+```ts
+function f(values: string[]) {}
+```
+
+## ✅ Correct
+
+```ts
+function f(values: readonly string[]) {}
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Common migration targets are `readonly T[]`, `readonly [A, B]`, or
+`ReadonlyArray<T>`.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+function parse(pair: [string, number]): void {}
+// ❌ reported
+
+function parseSafe(pair: readonly [string, number]): void {}
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/prefer-readonly-array": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if mutable arrays and tuples are preferred in your API design.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R107
+
+## Further reading
+
+- [TypeScript: ReadonlyArray<T>](https://www.typescriptlang.org/docs/handbook/interfaces.html#readonly-properties)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.