eslint-plugin-etc-misc 1.0.1

package/docs/rules/no-at-sign-internal-import.md

@@ -0,0 +1,98 @@
+# no-at-sign-internal-import
+
+Disallow internal alias imports under `"@/"`.
+
+## Targeted pattern scope
+
+This rule inspects module source strings in imports/exports and reports values
+matching the default disallow glob `"@/**"`.
+
+## What this rule reports
+
+This rule reports source strings that match `"@/**"`. It is useful when `@` should be reserved for package roots and not direct internal alias paths.
+
+## Why this rule exists
+
+If your architecture reserves `@` for package-level entrypoints only, this rule
+prevents deep internal alias imports.
+
+## ❌ Incorrect
+
+```ts
+import value from "@/feature";
+```
+
+## ✅ Correct
+
+```ts
+import value from "@";
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Typical migration is switching to package exports, public entrypoints, or
+allowed local relative imports.
+
+### Options
+
+```ts
+type Options = {
+    allow?: string[];
+    disallow?: string[];
+};
+```
+
+Default:
+
+```json
+{
+    "disallow": ["@/**"]
+}
+```
+
+## Additional examples
+
+```ts
+// default disallow: ["@/**"]
+import { helper } from "@/internal/helper";
+// ❌ reported
+
+import { helper } from "@";
+// ✅ not matched by default pattern
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-at-sign-internal-import": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if `@/` internal alias imports are part of your standard architecture.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R018
+
+## Further reading
+
+- [Node.js packages: entry points and exports](https://nodejs.org/api/packages.html#exports)
+
+## 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/no-chain-coalescence-mixture.md

@@ -0,0 +1,93 @@
+# no-chain-coalescence-mixture
+
+Disallow mixing optional chaining and nullish coalescing in one expression.
+
+## Targeted pattern scope
+
+This rule reports `LogicalExpression` nodes using `??` where the left-hand side
+is an optional chain (`ChainExpression`).
+
+In practice, it flags patterns like `obj?.value ?? fallback`.
+
+## What this rule reports
+
+This rule reports expressions like `foo?.bar ?? fallback`.
+
+## Why this rule exists
+
+Combining optional chaining and nullish coalescing inline can hide intent and
+make intermediate values harder to debug. Splitting steps improves readability.
+
+## ❌ Incorrect
+
+```ts
+foo?.bar ?? fallback;
+```
+
+## ✅ Correct
+
+```ts
+foo?.bar;
+foo ?? fallback;
+```
+
+```ts
+const value = foo?.bar;
+const result = value ?? fallback;
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Typical migration is introducing an intermediate variable before applying `??`.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+const title = config?.labels?.title ?? "Untitled";
+// ❌ reported
+
+const maybeTitle = config?.labels?.title;
+const titleSafe = maybeTitle ?? "Untitled";
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-chain-coalescence-mixture": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project permits `?.` and `??` in the same expression.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R019
+
+## Further reading
+
+- [MDN: Optional chaining (`?.`)](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Optional_chaining)
+- [MDN: Nullish coalescing (`??`)](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing)
+
+## 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/no-commented-out-code.md

@@ -0,0 +1,126 @@
+# no-commented-out-code
+
+Disallow comment blocks that appear to contain executable or declaration code.
+
+## Targeted pattern scope
+
+This rule analyzes all comments in the file (line and block) and tries to parse
+their content as code.
+
+It supports grouped consecutive line comments as one logical comment block.
+
+## What this rule reports
+
+Commented-out code creates maintenance noise, hides stale implementation paths,
+and can mislead readers into thinking dead code is still relevant.
+
+The rule reports comment blocks that parse as non-trivial code.
+
+The rule intentionally ignores non-code commentary patterns like region markers
+and plain prose notes.
+
+## Why this rule exists
+
+Keeping dead code in comments makes reviews and refactors harder. This rule
+helps enforce a cleaner baseline.
+
+## ❌ Incorrect
+
+```ts
+// const answer = 54;
+const answer = 42;
+```
+
+```ts
+class Example {
+    public a: string;
+    // public b: string;
+    public c: string;
+}
+```
+
+## ✅ Correct
+
+```ts
+// Explanation: historical implementation tried 54 first.
+const answer = 42;
+```
+
+```ts
+class Example {
+  // #region Public API
+  public execute(): void {}
+  // #endregion
+}
+```
+
+## Deprecated
+
+- **Lifecycle:** Deprecated and frozen.
+- **Deprecated since:** `v1.0.0`
+- **Available until:** `v2.0.0`
+- **Use instead:** [`no-commented-code/no-commented-code`](https://www.npmjs.com/package/eslint-plugin-no-commented-code)
+
+## Behavior and migration notes
+
+This rule is deprecated in favor of
+`no-commented-code/no-commented-code`.
+
+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
+// #region Helpers
+// #endregion
+// ✅ ignored as region marker comments
+
+// if (flag) {
+//   run();
+// }
+// ❌ reported as commented-out executable code
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-commented-out-code": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team intentionally keeps commented examples inline
+instead of using docs, snippets, or tests.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R020
+
+## Further reading
+
+- [ESLint: Working with Rules](https://eslint.org/docs/latest/extend/custom-rules)
+- [TypeScript-ESLint: Custom Rules](https://typescript-eslint.io/developers/custom-rules/)
+
+## 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/no-const-enum.md

@@ -0,0 +1,109 @@
+# no-const-enum
+
+Disallow TypeScript `const enum` declarations.
+
+## Targeted pattern scope
+
+This rule inspects `TSEnumDeclaration` nodes and reports when the declaration is
+marked `const`.
+
+With `allowLocal: true`, non-exported `const enum` declarations are allowed.
+
+## What this rule reports
+
+This rule reports `const enum` declarations. `const enum` relies on TypeScript-specific inlining behavior and can cause compatibility issues in mixed toolchains.
+
+## Why this rule exists
+
+`const enum` depends on compile-time inlining semantics that can break in mixed
+toolchains and isolated transpilation flows.
+
+## ❌ Incorrect
+
+```ts
+const enum Status {
+    Ready,
+    Running,
+}
+```
+
+## ✅ Correct
+
+```ts
+enum Status {
+    Ready,
+    Running,
+}
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Migration options:
+
+- convert `const enum` to regular `enum`, or
+- replace with `as const` object + union type.
+
+### Options
+
+```ts
+type Options = {
+    allowLocal?: boolean;
+};
+```
+
+Default: `{ allowLocal: false }`
+
+### `allowLocal`
+
+When `true`, non-exported `const enum` declarations are allowed.
+
+## Additional examples
+
+```ts
+// config: { allowLocal: true }
+const enum LocalKind {
+    A,
+}
+// ✅ allowed when not exported
+
+export const enum PublicKind {
+    A,
+}
+// ❌ still reported
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-const-enum": ["error", { allowLocal: true }],
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project explicitly depends on `const enum` inlining and your build toolchain guarantees consistent handling.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R021
+
+## Further reading
+
+- [TypeScript Handbook: Const enums](https://www.typescriptlang.org/docs/handbook/enums.html#const-enums)
+
+## 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/no-deprecated.md

@@ -0,0 +1,175 @@
+# no-deprecated
+
+Disallow usage of symbols tagged with `@deprecated`.
+
+## Targeted pattern scope
+
+⚠️ This rule requires type information to run. Configure type-aware linting (`parserOptions.project` or `projectService`) before enabling it.
+
+This rule inspects identifier *usages* and resolves each identifier to a
+TypeScript symbol.
+
+If the resolved symbol has one or more `@deprecated` JSDoc tags, usage is
+reported (unless ignored by configuration).
+
+## What this rule reports
+
+Deprecated APIs are still callable in TypeScript unless you add explicit checks.
+Using them silently accumulates technical debt and can cause breakage when those
+APIs are removed.
+
+This rule reports identifier usages whose resolved TypeScript symbol includes
+one or more `@deprecated` tags.
+
+## Why this rule exists
+
+It helps enforce deprecation cleanup and prevents new usage of APIs scheduled
+for removal.
+
+## ❌ Incorrect
+
+```ts
+/** @deprecated Use `newMethod` instead. */
+declare function oldMethod(): void;
+
+oldMethod();
+```
+
+```ts
+interface Api {
+  /** @deprecated Use `nextValue` instead. */
+  oldValue: string;
+}
+
+declare const api: Api;
+console.log(api.oldValue);
+```
+
+## ✅ Correct
+
+```ts
+declare function newMethod(): void;
+
+newMethod();
+```
+
+```ts
+/** @deprecated Legacy API retained for compatibility. */
+declare function legacyMethod(): void;
+
+// Declaration is allowed. Usage is reported.
+```
+
+## Deprecated
+
+- **Lifecycle:** Deprecated and frozen.
+- **Deprecated since:** `v1.0.0`
+- **Available until:** `v2.0.0`
+- **Use instead:** [`@typescript-eslint/no-deprecated`](https://typescript-eslint.io/rules/no-deprecated)
+
+## Behavior and migration notes
+
+This rule is deprecated in favor of `@typescript-eslint/no-deprecated`.
+
+It reports only and does not provide an autofix.
+
+### Options
+
+```ts
+type Options = [
+  {
+    ignored?: Record<string, "name" | "path">;
+  }?,
+];
+```
+
+Default:
+
+```ts
+[{}]
+```
+
+Use `ignored` to suppress some deprecated symbols by regular-expression pattern:
+
+- `"name"`: Match against the symbol name.
+- `"path"`: Match against the symbol's fully-qualified declaration path.
+
+If an `ignored` key is not a valid regular expression, the rule reports a
+configuration error (`invalidIgnorePattern`) instead of silently ignoring it.
+
+Example:
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+  {
+    plugins: { "etc-misc": etcMisc },
+    rules: {
+      "etc-misc/no-deprecated": [
+        "warn",
+        {
+          ignored: {
+            "^LegacyMethod$": "name",
+            "modules/legacy": "path",
+          },
+        },
+      ],
+    },
+  },
+];
+```
+
+### Status
+
+Use the **Deprecated** section above for lifecycle details.
+
+## Additional examples
+
+```ts
+/** @deprecated internal migration shim */
+declare const legacyApi: () => void;
+
+legacyApi();
+// ❌ reported
+
+// config: { ignored: { "^legacyApi$": "name" } }
+legacyApi();
+// ✅ ignored by option
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-deprecated": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project intentionally relies on deprecated APIs during
+a planned migration window and you want to manage those usages manually.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R022
+
+## Further reading
+
+- [TypeScript-ESLint: Typed Linting](https://typescript-eslint.io/getting-started/typed-linting)
+- [TSDoc: `@deprecated`](https://tsdoc.org/pages/tags/deprecated/)
+
+## 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/no-enum.md

@@ -0,0 +1,98 @@
+# no-enum
+
+Disallow TypeScript `enum` declarations.
+
+## Targeted pattern scope
+
+This rule reports every TypeScript `enum` declaration (`TSEnumDeclaration`).
+
+## What this rule reports
+
+This rule reports every `enum` declaration. Enums emit runtime JavaScript and can complicate tree-shaking and interop. In codebases that prefer structural typing, literal unions and `as const` objects are easier to reason about and maintain.
+
+## Why this rule exists
+
+It enforces enum-free TypeScript style where literal unions and `as const`
+objects are preferred over enum runtime constructs.
+
+## ❌ Incorrect
+
+```ts
+enum Status {
+    Ready,
+    Running,
+}
+```
+
+## ✅ Correct
+
+```ts
+const Status = {
+    Ready: "Ready",
+    Running: "Running",
+} as const;
+
+type Status = (typeof Status)[keyof typeof Status];
+```
+
+## Behavior and migration notes
+
+This rule reports only and does not provide an autofix.
+
+Migration is typically to `as const` object patterns plus derived union types.
+
+### Options
+
+This rule has no options.
+
+## Additional examples
+
+```ts
+enum HttpCode {
+    Ok = 200,
+    NotFound = 404,
+}
+// ❌ reported
+
+const HttpCode = {
+    Ok: 200,
+    NotFound: 404,
+} as const;
+
+type HttpCode = (typeof HttpCode)[keyof typeof HttpCode];
+// ✅ valid
+```
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-enum": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project intentionally standardizes on TypeScript enums and accepts their emitted runtime output.
+
+## Package documentation
+
+- [eslint-plugin-etc-misc README](https://github.com/Nick2bad4u/eslint-plugin-etc-misc#readme)
+
+> **Rule catalog ID:** R023
+
+## Further reading
+
+- [TypeScript Handbook: Enums](https://www.typescriptlang.org/docs/handbook/enums.html)
+
+## Adoption resources
+
+- Start at warning level in CI, then move to error after cleanup.
+- Use focused codemods/autofix batches per package or directory.