eslint-plugin-etc-misc 1.0.1

package/docs/rules/consistent-import.md

@@ -0,0 +1,128 @@
+# consistent-import
+
+Enforce consistent import declaration style.
+
+## Targeted pattern scope
+
+This rule analyzes `ImportDeclaration` nodes and compares import specifier shape
+for each module source string.
+
+It distinguishes five styles:
+
+- `side-effect`: `import "x";`
+- `default`: `import x from "x";`
+- `named`: `import { x } from "x";`
+- `mixed`: `import x, { y } from "x";`
+- `namespace`: `import * as x from "x";`
+
+## What this rule reports
+
+This rule reports imports whose style does not match the expected style.
+
+- Without options, the first import style seen for a given module source becomes
+the expected style for subsequent imports from that same source.
+- With `style`, all imports must match the configured style globally.
+
+## Why this rule exists
+
+Mixing import styles for the same module creates unnecessary visual noise and can
+hide duplicate or redundant imports. A consistent style improves readability and
+keeps import blocks predictable.
+
+## ❌ Incorrect
+
+```ts
+import fs from "node:fs";
+import { readFileSync } from "node:fs";
+//                      ^^^^^^^^^^^^^^ second import style differs for same source
+```
+
+## ✅ Correct
+
+```ts
+import fs from "node:fs";
+import path from "node:path";
+```
+
+```ts
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+```
+
+## Behavior and migration notes
+
+This rule has no autofix because changing import style can require coordinated
+identifier updates.
+
+Adopt safely by selecting one preferred style and applying codemods (or manual
+cleanup) before promoting from `warn` to `error`.
+
+### Options
+
+```ts
+type Options = [
+    {
+        style?: "default" | "mixed" | "named" | "namespace" | "side-effect";
+    },
+];
+```
+
+- `style` (optional): enforce one style for all import declarations.
+
+### Default configuration
+
+```ts
+[{}]
+```
+
+When `style` is omitted, the first seen import style for each module source is
+treated as that source's expected style.
+
+Example:
+
+```ts
+"etc-misc/consistent-import": ["error", { style: "named" }];
+```
+
+## Additional examples
+
+```ts
+import "reflect-metadata";
+import "reflect-metadata";
+// Consistent side-effect style for the same source.
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/consistent-import": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally mixes import styles for the
+same module (for example, staged migration from default to named exports).
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R007
+
+## Further reading
+
+- [MDN: `import`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/import)
+
+## 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/consistent-optional-props.md

@@ -0,0 +1,114 @@
+# consistent-optional-props
+
+Disallow redundant undefined unions on optional properties.
+
+## Targeted pattern scope
+
+This rule targets optional properties that redundantly include `undefined` in
+their union type.
+
+Covered nodes include:
+
+- interface/type property signatures (`TSPropertySignature`), and
+- class property definitions (`PropertyDefinition`).
+
+## What this rule reports
+
+This rule reports `?` properties whose type union explicitly includes
+`undefined`.
+
+Example pattern:
+
+```ts
+name?: string | undefined;
+```
+
+Because `?` already implies `undefined`, the explicit union member is redundant.
+
+## Why this rule exists
+
+Removing redundant `undefined` unions keeps type declarations smaller and easier
+to read.
+
+## ❌ Incorrect
+
+```ts
+interface User {
+    name?: string | undefined;
+}
+
+class Config {
+    timeoutMs?: number | undefined;
+}
+```
+
+## ✅ Correct
+
+```ts
+interface User {
+    name?: string;
+}
+
+class Config {
+    timeoutMs?: number;
+}
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Migration is straightforward: remove `| undefined` from optional properties.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+type Options = {
+    verbose?: boolean | undefined;
+};
+// ❌ reported
+
+type OptionsFixed = {
+    verbose?: boolean;
+};
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/consistent-optional-props": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally keeps explicit
+`| undefined` unions for documentation style.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R008
+
+## Further reading
+
+- [TypeScript: Optional Properties](https://www.typescriptlang.org/docs/handbook/interfaces.html#optional-properties)
+
+## 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/consistent-source-extension.md

@@ -0,0 +1,106 @@
+# consistent-source-extension
+
+Require consistent import/export source paths without file extensions.
+
+## Targeted pattern scope
+
+This rule reports string-literal module sources that end with these explicit
+extensions:
+
+- `.js`
+- `.json`
+- `.ts`
+
+It applies to import/export sources and any matching source literal in supported
+module syntax nodes.
+
+## What this rule reports
+
+This rule reports import/export paths that end with `.js`, `.json`, or `.ts`.
+
+## Why this rule exists
+
+Teams that standardize extensionless internal specifiers use this rule to keep
+import/export declarations consistent.
+
+## ❌ Incorrect
+
+```ts
+import x1 from "source.js";
+import x2 from "source.json";
+import x3 from "source.ts";
+```
+
+## ✅ Correct
+
+```ts
+import x1 from "source";
+import x2 from "source";
+import x3 from "source";
+```
+
+## Deprecated
+
+- **Lifecycle:** Deprecated and frozen.
+- **Deprecated since:** `v1.0.0`
+- **Available until:** `v2.0.0`
+- **Use instead:** [`import/extensions`](https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/extensions.md)
+
+## Behavior and migration notes
+
+This rule is deprecated in favor of `import/extensions`.
+
+It reports only and does not provide an autofix.
+
+### Options
+
+This rule has no options.
+
+### Status
+
+Use the **Deprecated** section above for lifecycle details.
+
+## Additional examples
+
+```ts
+export * from "./utils.ts";
+// ❌ reported
+
+export * from "./utils";
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/consistent-source-extension": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your module resolver requires explicit source file extensions.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R009
+
+## Further reading
+
+- [TypeScript: `moduleResolution` reference](https://www.typescriptlang.org/tsconfig/#moduleResolution)
+- [Node.js ECMAScript modules](https://nodejs.org/api/esm.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/consistent-symbol-description.md

@@ -0,0 +1,91 @@
+# consistent-symbol-description
+
+Require consistent kebab-case Symbol descriptions.
+
+## Targeted pattern scope
+
+This rule inspects `Symbol("...")` calls where the description argument is a
+string literal.
+
+Descriptions must match this kebab-style character set:
+
+- lowercase letters (`a-z`)
+- digits (`0-9`)
+- hyphen (`-`)
+- double underscore separator (`__`)
+
+## What this rule reports
+
+This rule reports `Symbol(...)` descriptions that are not lower-case kebab-case (with optional double-underscore separators).
+
+## Why this rule exists
+
+Consistent symbol descriptions improve debugging output and cross-module symbol
+naming hygiene.
+
+## ❌ Incorrect
+
+```ts
+const x = Symbol("PascalCase");
+const y = Symbol("contains spaces");
+```
+
+## ✅ Correct
+
+```ts
+const x = Symbol("kebab-case__kebab-case");
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Migrate by renaming descriptions to lowercase kebab-style tokens.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+const id = Symbol("cache-key__v2");
+// ✅ valid
+
+const bad = Symbol("Cache_Key");
+// ❌ reported
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/consistent-symbol-description": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally allows other naming styles for Symbol descriptions.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R010
+
+## Further reading
+
+- [MDN: `Symbol()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol/Symbol)
+
+## 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/default-case.md

@@ -0,0 +1,95 @@
+# default-case
+
+Require a `default` branch in `switch` statements.
+
+## Targeted pattern scope
+
+This rule targets all JavaScript and TypeScript `switch` statements.
+
+## What this rule reports
+
+This rule reports `switch` statements that do not include a `default` case.
+
+## Why this rule exists
+
+Missing defaults can silently ignore unexpected values and create fragile
+control flow.
+
+## ❌ Incorrect
+
+```ts
+switch (status) {
+    case "open":
+        break;
+}
+```
+
+## ✅ Correct
+
+```ts
+switch (status) {
+    case "open":
+        break;
+    default:
+        break;
+}
+```
+
+## Behavior and migration notes
+
+This rule forwards options and behavior to ESLint core `default-case`.
+
+## Additional examples
+
+```ts
+switch (kind) {
+    case "a":
+        runA();
+        break;
+}
+// ❌ reported
+
+switch (kind) {
+    case "a":
+        runA();
+        break;
+    default:
+        throw new Error(`Unhandled kind: ${kind}`);
+}
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/default-case": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if you enforce exhaustive unions with explicit `never`
+checks and intentionally avoid `default` branches.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R011
+
+## Further reading
+
+- [ESLint: `default-case`](https://eslint.org/docs/latest/rules/default-case)
+
+## 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/disallow-import.md

@@ -0,0 +1,108 @@
+# disallow-import
+
+Disallow import/export sources by configured glob patterns.
+
+## Targeted pattern scope
+
+This rule checks module source strings in:
+
+- `import ... from "..."`
+- `export ... from "..."`
+- `export * from "..."`
+- dynamic `import("...")`
+
+It matches those source values against glob patterns.
+
+## What this rule reports
+
+This rule matches import and export source values against `disallow` globs, with optional `allow` exceptions.
+
+## Why this rule exists
+
+This rule is a general boundary primitive: it lets you ban path families and
+optionally carve out explicit exceptions.
+
+## ❌ Incorrect
+
+```ts
+import value from "../source";
+```
+
+with options:
+
+```ts
+{ disallow: ["../**"] }
+```
+
+## ✅ Correct
+
+```ts
+import value from "../source";
+```
+
+with options:
+
+```ts
+{ disallow: ["../**"], allow: ["../source"] }
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Because the default `disallow` set is empty, this rule does nothing until you
+configure `disallow` patterns.
+
+### Options
+
+```ts
+type Options = {
+    allow?: string[];
+    disallow?: string[];
+};
+```
+
+## Additional examples
+
+```ts
+// config: { disallow: ["../**"], allow: ["../shared/**"] }
+import util from "../feature/util";
+// ❌ reported
+
+import shared from "../shared/math";
+// ✅ allowed by explicit exception
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/disallow-import": ["error", { disallow: ["../**"] }],
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project does not enforce import path restrictions.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R012
+
+## Further reading
+
+- [minimatch glob pattern reference](https://github.com/isaacs/minimatch)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.