eslint-plugin-th-rules 1.15.6 → 1.16.0

package/.yarnrc.yml

@@ -1,3 +1,3 @@
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-4.6.0.cjs
+yarnPath: .yarn/releases/yarn-4.12.0.cjs

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.16.0](https://github.com/tomerh2001/eslint-plugin-th-rules/compare/v1.15.6...v1.16.0) (2026-01-05)
+
+
+### Features
+
+* add new rule 'types-in-dts' to enforce TypeScript type declarations in .d.ts files ([00c4769](https://github.com/tomerh2001/eslint-plugin-th-rules/commit/00c4769f9a025642f7c72023df1dea82dbf33e72))
+
 ## [1.15.6](https://github.com/tomerh2001/eslint-plugin-th-rules/compare/v1.15.5...v1.15.6) (2024-12-30)
 
 

package/README.md

@@ -7,10 +7,6 @@
 
 This repository contains custom ESLint rules to enhance code quality and consistency across projects.
 
-# Custom ESLint Rules
-
-This repository contains custom ESLint rules to enhance code quality and consistency across projects, created by Tomer Horowitz.
-
 ## Rules
 <!-- begin auto-generated rules list -->
 
@@ -18,12 +14,13 @@ This repository contains custom ESLint rules to enhance code quality and consist
 ✅ Set in the `recommended` configuration.\
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).
 
-| Name                                                     | Description                                                                      | 💼                                                               | 🔧 |
-| :------------------------------------------------------- | :------------------------------------------------------------------------------- | :--------------------------------------------------------------- | :- |
-| [no-comments](docs/rules/no-comments.md)                 | Disallow comments except for specified allowed patterns.                         | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] | 🔧 |
-| [no-default-export](docs/rules/no-default-export.md)     | Convert unnamed default exports to named default exports based on the file name. | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] | 🔧 |
-| [no-destructuring](docs/rules/no-destructuring.md)       | Disallow destructuring that does not meet certain conditions                     | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] |    |
-| [top-level-functions](docs/rules/top-level-functions.md) | Require all top-level functions to be named/regular functions.                   |                                                                  | 🔧 |
+| Name                                                     | Description                                                                            | 💼                                                               | 🔧 |
+| :------------------------------------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------------------------------------- | :- |
+| [no-comments](docs/rules/no-comments.md)                 | Disallow comments except for specified allowed patterns.                               | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] | 🔧 |
+| [no-default-export](docs/rules/no-default-export.md)     | Convert unnamed default exports to named default exports based on the file name.       | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] | 🔧 |
+| [no-destructuring](docs/rules/no-destructuring.md)       | Disallow destructuring that does not meet certain conditions                           | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] |    |
+| [top-level-functions](docs/rules/top-level-functions.md) | Require all top-level functions to be named/regular functions.                         | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] | 🔧 |
+| [types-in-dts](docs/rules/types-in-dts.md)               | Require TypeScript type declarations (type/interface/enum) to be placed in .d.ts files | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] |    |
 
 <!-- end auto-generated rules list -->
 

package/docs/rules/top-level-functions.md

@@ -1,5 +1,7 @@
 # Require all top-level functions to be named/regular functions (`th-rules/top-level-functions`)
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, `recommended-react`, `recommended-typescript`.
+
 🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
 <!-- end auto-generated rule header -->
@@ -38,9 +40,6 @@ function myFunction() {
 }
 ```
 
-## Options
-
-This rule has no options.
 
 ## When Not To Use It
 

package/docs/rules/types-in-dts.md

@@ -0,0 +1,112 @@
+<pre>
+# Require TypeScript type declarations (type/interface/enum) to be placed in .d.ts files (`th-rules/types-in-dts`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, `recommended-react`, `recommended-typescript`.
+
+<!-- end auto-generated rule header -->
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, `recommended-react`, `recommended-typescript`.
+
+&lt;!-- end auto-generated rule header --&gt;
+
+This rule enforces a strict separation between **runtime code** and **type declarations** by requiring all top-level TypeScript type declarations to be defined in `.d.ts` files.
+
+The rule applies to:
+- `type` aliases
+- `interface` declarations
+- `enum` declarations
+
+Any of these constructs declared outside of a `.d.ts` file will be reported, unless explicitly allowed via configuration.
+
+## Rationale
+
+Keeping type declarations in `.d.ts` files provides several benefits:
+
+- Enforces a clean architectural boundary between runtime logic and type definitions
+- Improves file readability by reducing noise in implementation files
+- Encourages intentional, centralized ownership of public and shared types
+- Prevents accidental runtime coupling with type-only constructs
+- Aligns well with library-oriented or API-driven codebases
+
+This rule is especially useful in large TypeScript projects, shared packages, or monorepos where type contracts are meant to be consumed independently of implementation.
+
+## Examples
+
+### ❌ Incorrect
+
+```ts
+// user.ts
+type UserId = string;
+
+interface User {
+  id: UserId;
+  name: string;
+}
+
+enum Role {
+  Admin,
+  User,
+}
+```
+
+### ✅ Correct
+
+```ts
+// user.d.ts
+type UserId = string;
+
+interface User {
+  id: UserId;
+  name: string;
+}
+
+enum Role {
+  Admin,
+  User,
+}
+```
+
+```ts
+// user.ts
+import type { User, UserId, Role } from './user';
+```
+
+### Allowed usage
+
+Using types, interfaces, or enums is always allowed in any file:
+
+```ts
+function getUser(id: UserId): User {
+  // ...
+}
+```
+
+## Options
+
+&lt;!-- begin auto-generated rule options list --&gt;
+
+| Name           | Type    |
+| :------------- | :------ |
+| `allowDeclare` | Boolean |
+| `allowEnums`   | Boolean |
+
+&lt;!-- end auto-generated rule options list --&gt;
+
+### `allowDeclare`
+
+When set to `true`, the rule allows `declare` type declarations in non-`.d.ts` files.
+
+This is useful when working with ambient declarations, global augmentations, or compatibility shims that must live alongside implementation code.
+
+### `allowEnums`
+
+When set to `true`, the rule allows `enum` declarations in non-`.d.ts` files.
+
+This can be helpful in codebases that rely on runtime enums while still wanting to enforce `.d.ts` placement for interfaces and type aliases.
+
+## Notes
+
+- This rule does not enforce how types are imported or re-exported.
+- It does not attempt to auto-fix violations, as moving declarations across files is not safe to do automatically.
+- The rule operates purely at the syntax level and does not require type information.
+</pre>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-th-rules",
-  "version": "1.15.6",
+  "version": "1.16.0",
   "description": "A List of custom ESLint rules created by Tomer Horowitz",
   "keywords": [
     "eslint",
@@ -49,7 +49,7 @@
     "eslint-plugin-eslint-plugin": "^6.4.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-sonarjs": "^3.0.1",
-    "eslint-plugin-th-rules": "1.14.1",
+    "eslint-plugin-th-rules": "1.15.6",
     "eslint-plugin-unicorn": "^56.0.1",
     "mocha": "^11.0.1",
     "npm-run-all": "^4.1.5",
@@ -62,5 +62,5 @@
     "typescript": "^5.7.2"
   },
   "license": "ISC",
-  "packageManager": "yarn@4.6.0"
+  "packageManager": "yarn@4.12.0"
 }

package/src/index.js

@@ -19,6 +19,7 @@ const configs = {
 			'th-rules/no-default-export': 'error',
 			'th-rules/no-comments': 'error',
 			'th-rules/top-level-functions': 'error',
+			'th-rules/types-in-dts': 'error',
 			'unicorn/prefer-module': 'warn',
 			'unicorn/filename-case': 'off',
 			'unicorn/no-array-callback-reference': 'off',

package/src/rules/top-level-functions.js

@@ -67,7 +67,6 @@ function buildFunctionExpressionReplacement(functionName, functionExprNode, sour
  */
 function buildAnonymousFunctionDeclarationReplacement(sourceCode, node, functionName = 'defaultFunction', isExport = false) {
 	const originalText = sourceCode.getText(node);
-	const asyncKeyword = node.async ? 'async ' : '';
 	const exportKeyword = isExport ? 'export ' : '';
 
 	let replaced = originalText;

package/src/rules/types-in-dts.js

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Enforce that TypeScript type declarations exist only in .d.ts files.
+ */
+
+const meta = {
+	type: 'problem',
+	docs: {
+		description: 'Require TypeScript type declarations (type/interface/enum) to be placed in .d.ts files',
+		category: 'Best Practices',
+		recommended: true,
+		url: 'https://github.com/tomerh2001/eslint-plugin-th-rules/blob/main/docs/rules/types-in-dts.md',
+	},
+	schema: [
+		{
+			type: 'object',
+			properties: {
+				allowEnums: {type: 'boolean'},
+				allowDeclare: {type: 'boolean'},
+			},
+			additionalProperties: false,
+		},
+	],
+	messages: {
+		moveToDts:
+			'Type declarations must be moved to a .d.ts file (for example "{{filename}}.d.ts").',
+	},
+};
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ */
+function create(context) {
+	const options = context.options?.[0] ?? {};
+	const allowEnums = Boolean(options.allowEnums);
+	const allowDeclare = Boolean(options.allowDeclare);
+
+	function isDtsFile(filename) {
+		if (!filename || filename === '<input>') {
+			return false;
+		}
+
+		return filename.endsWith('.d.ts');
+	}
+
+	function hasDeclareModifier(node) {
+		if (node && node.declare === true) {
+			return true;
+		}
+
+		const mods = node && Array.isArray(node.modifiers) ? node.modifiers : [];
+		return mods.some(m => m && m.type === 'TSDeclareKeyword');
+	}
+
+	function reportIfNotDts(node) {
+		const filename = context.getFilename();
+		if (isDtsFile(filename)) {
+			return;
+		}
+
+		if (allowDeclare && hasDeclareModifier(node)) {
+			return;
+		}
+
+		context.report({
+			node,
+			messageId: 'moveToDts',
+			data: {filename},
+		});
+	}
+
+	return {
+
+		TSTypeAliasDeclaration(node) {
+			reportIfNotDts(node);
+		},
+
+		TSInterfaceDeclaration(node) {
+			reportIfNotDts(node);
+		},
+
+		TSEnumDeclaration(node) {
+			if (allowEnums) {
+				return;
+			}
+
+			reportIfNotDts(node);
+		},
+
+	};
+}
+
+module.exports = {
+	meta,
+	create,
+};