eslint-plugin-etc-misc 1.0.1

package/docs/rules/typescript-require-readonly-array-return-type.md

@@ -0,0 +1,113 @@
+# typescript/require-readonly-array-return-type
+
+Require readonly array-like types for function and method return annotations.
+
+## Targeted pattern scope
+
+This rule targets top-level array-like return type annotations, including:
+
+- `T[]`
+- tuple types (`[A, B]`)
+- `Array<T>`
+- union/intersection members such as `T[] | null`
+
+It checks function declarations, function expressions, arrow functions with return
+annotations, call/method signatures, and constructor/function type nodes.
+
+## What this rule reports
+
+This rule reports return type annotations that use mutable array-like types.
+
+## Why this rule exists
+
+Return types define API contracts. Returning readonly array-like types signals
+immutability to consumers and prevents accidental mutation at call sites.
+
+## ❌ Incorrect
+
+```ts
+function getNames(): string[] {
+    return [];
+}
+
+type PairFactory = () => [string, number];
+
+interface Api {
+    run(): Array<string>;
+}
+```
+
+## ✅ Correct
+
+```ts
+function getNames(): readonly string[] {
+    return [];
+}
+
+type PairFactory = () => readonly [string, number];
+
+interface Api {
+    run(): 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 return types (and top-level
+union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+type Resolver = () => string[] | null;
+// ❌ reported
+
+type Resolver = () => readonly string[] | null;
+// ✅ valid
+
+function getConfig(): { values: string[] } {
+    return { values: [] };
+}
+// ✅ 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/require-readonly-array-return-type": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally returns mutable arrays and you
+prefer not to expose readonly return contracts.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R116
+
+## 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-require-readonly-array-type-alias.md

@@ -0,0 +1,102 @@
+# typescript/require-readonly-array-type-alias
+
+Require readonly array-like types in type alias annotations.
+
+## Targeted pattern scope
+
+This rule targets top-level array-like type alias annotations, including:
+
+- `T[]`
+- tuple types (`[A, B]`)
+- `Array<T>`
+- union/intersection members such as `T[] | null`
+
+It checks only the type annotation attached to `type` aliases.
+
+## What this rule reports
+
+This rule reports type alias annotations that use mutable array-like types.
+
+## Why this rule exists
+
+Type aliases often define reusable API contracts. Using readonly array-like types
+in aliases helps propagate immutability expectations to all downstream uses.
+
+## ❌ Incorrect
+
+```ts
+type Names = string[];
+
+type Pair = [string, number];
+
+type Registry = Array<string>;
+```
+
+## ✅ Correct
+
+```ts
+type Names = readonly string[];
+
+type Pair = readonly [string, number];
+
+type Registry = 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 type alias annotations (and
+top-level union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+type Resolver = string[] | null;
+// ❌ reported
+
+type Resolver = readonly string[] | null;
+// ✅ valid
+
+type Config = { values: string[] };
+// ✅ 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/require-readonly-array-type-alias": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally uses mutable array type aliases
+or if you already enforce immutability through a broader rule strategy.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R117
+
+## 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-require-readonly-map-parameter-type.md

@@ -0,0 +1,99 @@
+# typescript/require-readonly-map-parameter-type
+
+Require `ReadonlyMap` for function and method parameter type annotations.
+
+## Targeted pattern scope
+
+This rule targets top-level mutable `Map<...>` parameter type annotations,
+including top-level union/intersection members such as `Map<K, V> | null`.
+
+It checks function declarations, function expressions, arrow functions,
+call/method signatures, and constructor/function type nodes (including
+constructor parameter properties).
+
+## What this rule reports
+
+This rule reports parameter annotations that use mutable `Map<...>`.
+
+## Why this rule exists
+
+Parameter types define API input contracts. Using `ReadonlyMap` for parameters
+communicates non-mutating expectations and helps avoid accidental argument
+mutation.
+
+## ❌ Incorrect
+
+```ts
+function loadIndex(index: Map<string, number>): void {}
+
+const resolver = (index: Map<string, number> | null) => index;
+
+class Registry {
+    constructor(private readonly table: Map<string, string>) {}
+}
+```
+
+## ✅ Correct
+
+```ts
+function loadIndex(index: ReadonlyMap<string, number>): void {}
+
+const resolver = (index: ReadonlyMap<string, number> | null) => index;
+
+class Registry {
+    constructor(private readonly table: ReadonlyMap<string, string>) {}
+}
+```
+
+## Behavior and migration notes
+
+This rule is autofixable and also provides suggestions.
+
+- `Map<K, V>` is converted to `ReadonlyMap<K, V>`.
+- The rule intentionally checks only top-level parameter types (and top-level
+  union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+function configure(options: { index: Map<string, number> }): void {}
+// ✅ valid (nested property type is out of scope)
+
+function configure(index?: ReadonlyMap<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/require-readonly-map-parameter-type": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally mutates map inputs or if you
+already enforce a broader readonly parameter policy via type-aware linting.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R118
+
+## Further reading
+
+- [TypeScript: ReadonlyMap<K, V>](https://www.typescriptlang.org/docs/handbook/utility-types.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-require-readonly-map-property-type.md

@@ -0,0 +1,103 @@
+# typescript/require-readonly-map-property-type
+
+Require `ReadonlyMap` for top-level property type annotations.
+
+## Targeted pattern scope
+
+This rule targets top-level mutable `Map<K, V>` property type annotations,
+including top-level union/intersection members such as
+`Map<string, number> | null`.
+
+It checks property signatures in interfaces and type literals.
+
+## What this rule reports
+
+This rule reports property annotations that use mutable `Map<...>`.
+
+## Why this rule exists
+
+Property signatures define object contracts consumed across your codebase.
+Using `ReadonlyMap` for these property types communicates immutability intent
+and helps avoid accidental mutation through shared map-like data.
+
+## ❌ Incorrect
+
+```ts
+interface Config {
+    lookup: Map<string, number>;
+}
+
+type ApiConfig = {
+    lookup: Map<string, number> | null;
+};
+```
+
+## ✅ Correct
+
+```ts
+interface Config {
+    lookup: ReadonlyMap<string, number>;
+}
+
+type ApiConfig = {
+    lookup: ReadonlyMap<string, number> | null;
+};
+```
+
+## Behavior and migration notes
+
+This rule is autofixable and also provides suggestions.
+
+- `Map<K, V>` is converted to `ReadonlyMap<K, V>`.
+- The rule intentionally checks only top-level property type annotations (and
+  top-level union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+interface Config {
+    lookup: Promise<Map<string, number>>;
+}
+// ✅ valid (nested generic type is out of scope)
+
+type Settings = {
+    lookup: { nested: Map<string, number> };
+};
+// ✅ 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/require-readonly-map-property-type": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally models property maps as
+mutable or if broader readonly policies already enforce your preferred
+constraints.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R119
+
+## Further reading
+
+- [TypeScript: ReadonlyMap<K, V>](https://www.typescriptlang.org/docs/handbook/utility-types.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-require-readonly-map-return-type.md

@@ -0,0 +1,105 @@
+# typescript/require-readonly-map-return-type
+
+Require `ReadonlyMap` for function and method return type annotations.
+
+## Targeted pattern scope
+
+This rule targets top-level mutable `Map<...>` return type annotations,
+including top-level union/intersection members such as `Map<K, V> | null`.
+
+It checks function declarations, function expressions, arrow functions with
+return annotations, call/method signatures, and constructor/function type nodes.
+
+## What this rule reports
+
+This rule reports return type annotations that use mutable `Map<...>`.
+
+## Why this rule exists
+
+Return types define API contracts. Returning `ReadonlyMap` communicates
+non-mutating intent to callers and reduces accidental mutation of shared maps.
+
+## ❌ Incorrect
+
+```ts
+function buildLookup(): Map<string, number> {
+    return new Map();
+}
+
+type Resolver = () => Map<string, string> | null;
+
+interface API {
+    run(): Map<string, string>;
+}
+```
+
+## ✅ Correct
+
+```ts
+function buildLookup(): ReadonlyMap<string, number> {
+    return new Map();
+}
+
+type Resolver = () => ReadonlyMap<string, string> | null;
+
+interface API {
+    run(): ReadonlyMap<string, string>;
+}
+```
+
+## Behavior and migration notes
+
+This rule is autofixable and also provides suggestions.
+
+- `Map<K, V>` is converted to `ReadonlyMap<K, V>`.
+- The rule intentionally checks only top-level return types (and top-level
+  union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+function buildConfig(): Promise<Map<string, string>> {
+    return Promise.resolve(new Map());
+}
+// ✅ valid (nested generic type is out of scope)
+
+function buildState(): { values: Map<string, string> } {
+    return { values: new Map() };
+}
+// ✅ valid (nested object-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/require-readonly-map-return-type": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally exposes mutable `Map` return
+types or if you already enforce broader readonly type policy at the same scope.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R120
+
+## Further reading
+
+- [TypeScript: ReadonlyMap<K, V>](https://www.typescriptlang.org/docs/handbook/utility-types.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-require-readonly-map-type-alias.md

@@ -0,0 +1,92 @@
+# typescript/require-readonly-map-type-alias
+
+Require readonly map types in type alias annotations.
+
+## Targeted pattern scope
+
+This rule targets top-level `Map<K, V>` type alias annotations, including
+union/intersection members such as `Map<K, V> | null`.
+
+It checks only the type annotation attached to `type` aliases.
+
+## What this rule reports
+
+This rule reports type alias annotations that use mutable `Map<...>`.
+
+## Why this rule exists
+
+Type aliases often define reusable API contracts. Using `ReadonlyMap` in alias
+annotations communicates immutability expectations to all downstream uses.
+
+## ❌ Incorrect
+
+```ts
+type Lookup = Map<string, number>;
+
+type MaybeLookup = Map<string, number> | null;
+
+type Combined = Map<string, number> & { readonly kind: "ok" };
+```
+
+## ✅ Correct
+
+```ts
+type Lookup = ReadonlyMap<string, number>;
+
+type MaybeLookup = ReadonlyMap<string, number> | null;
+
+type Combined = ReadonlyMap<string, number> & { readonly kind: "ok" };
+```
+
+## Behavior and migration notes
+
+This rule is autofixable and also provides suggestions.
+
+- `Map<K, V>` is converted to `ReadonlyMap<K, V>`.
+- The rule intentionally checks only top-level type alias annotations (and
+  top-level union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+type Resolver = Promise<Map<string, number>>;
+// ✅ valid (nested generic type is out of scope)
+
+type Config = { lookup: Map<string, number> };
+// ✅ 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/require-readonly-map-type-alias": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally uses mutable map aliases or if
+you already enforce immutability through a broader rule strategy.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R121
+
+## Further reading
+
+- [TypeScript: ReadonlyMap<K, V>](https://www.typescriptlang.org/docs/handbook/utility-types.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-require-readonly-record-parameter-type.md

@@ -0,0 +1,100 @@
+# typescript/require-readonly-record-parameter-type
+
+Require `Readonly<Record<...>>` for function and method parameter type annotations.
+
+## Targeted pattern scope
+
+This rule targets top-level mutable `Record<K, V>` parameter type annotations,
+including top-level union/intersection members such as
+`Record<string, string> | null`.
+
+It checks function declarations, function expressions, arrow functions,
+call/method signatures, and constructor/function type nodes (including
+constructor parameter properties).
+
+## What this rule reports
+
+This rule reports parameter annotations that use mutable `Record<...>`.
+
+## Why this rule exists
+
+Parameter types define API input contracts. Using `Readonly<Record<...>>` for
+parameters communicates non-mutating expectations and helps avoid accidental
+argument mutation.
+
+## ❌ Incorrect
+
+```ts
+function loadLookup(lookup: Record<string, string>): void {}
+
+const resolver = (lookup: Record<string, string> | null) => lookup;
+
+class Registry {
+    constructor(private readonly lookup: Record<string, string>) {}
+}
+```
+
+## ✅ Correct
+
+```ts
+function loadLookup(lookup: Readonly<Record<string, string>>): void {}
+
+const resolver = (lookup: Readonly<Record<string, string>> | null) => lookup;
+
+class Registry {
+    constructor(private readonly lookup: Readonly<Record<string, string>>) {}
+}
+```
+
+## Behavior and migration notes
+
+This rule is autofixable and also provides suggestions.
+
+- `Record<K, V>` is converted to `Readonly<Record<K, V>>`.
+- The rule intentionally checks only top-level parameter types (and top-level
+  union/intersection members), not nested object-property types.
+
+## Additional examples
+
+```ts
+function configure(options: { lookup: Record<string, string> }): void {}
+// ✅ valid (nested property type is out of scope)
+
+function configure(lookup?: Readonly<Record<string, string>>): void {}
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/typescript/require-readonly-record-parameter-type": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally mutates record inputs or if
+you already enforce a broader readonly parameter policy via type-aware linting.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R122
+
+## Further reading
+
+- [TypeScript Utility Types: `Readonly<Type>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.