eslint-plugin-th-rules 1.15.5 → 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,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* enhance top-level functions rule to support async and export keywords ([cca9ceb](https://github.com/tomerh2001/eslint-plugin-th-rules/commit/cca9cebe77fa01820048a55c444e55bd297b883c))
+
 ## [1.15.5](https://github.com/tomerh2001/eslint-plugin-th-rules/compare/v1.15.4...v1.15.5) (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.5",
+  "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

@@ -1,16 +1,5 @@
 /* eslint-disable unicorn/prefer-module */
 
-/**
- * @type {Object}
- * @property {string} type - The type of the rule, in this case, 'suggestion'.
- * @property {Object} docs - Documentation related to the rule.
- * @property {string} docs.description - A brief description of the rule.
- * @property {string} docs.category - The category of the rule, 'Stylistic Issues'.
- * @property {boolean} docs.recommended - Indicates if the rule is recommended.
- * @property {string} docs.url - The URL to the documentation of the rule.
- * @property {string} fixable - Indicates if the rule is fixable, 'code'.
- * @property {Array} schema - The schema for the rule options.
- */
 const meta = {
 	type: 'suggestion',
 	docs: {
@@ -29,10 +18,13 @@ const meta = {
  * @param {string} funcName - The name of the new function.
  * @param {ArrowFunctionExpression} arrowNode - The ArrowFunctionExpression node.
  * @param {import('eslint').SourceCode} sourceCode - The ESLint SourceCode object.
- * @param {boolean} isExport - Whether or not this function is exported.
+ * @param {boolean} isExport - Whether or not this function is exported (e.g., `export const foo = ...`).
  * @returns {string} The replacement code.
  */
 function buildArrowFunctionReplacement(functionName, arrowNode, sourceCode, isExport) {
+	const asyncKeyword = arrowNode.async ? 'async ' : '';
+	const exportKeyword = isExport ? 'export ' : '';
+
 	const parametersText = arrowNode.params.map(parameter => sourceCode.getText(parameter)).join(', ');
 
 	let bodyText;
@@ -43,8 +35,7 @@ function buildArrowFunctionReplacement(functionName, arrowNode, sourceCode, isEx
 		bodyText = `{ return ${expressionText}; }`;
 	}
 
-	const exportKeyword = isExport ? 'export ' : '';
-	return `${exportKeyword}function ${functionName}(${parametersText}) ${bodyText}`;
+	return `${exportKeyword}${asyncKeyword}function ${functionName}(${parametersText}) ${bodyText}`;
 }
 
 /**
@@ -57,36 +48,40 @@ function buildArrowFunctionReplacement(functionName, arrowNode, sourceCode, isEx
  * @returns {string} The replacement code.
  */
 function buildFunctionExpressionReplacement(functionName, functionExprNode, sourceCode, isExport) {
+	const asyncKeyword = functionExprNode.async ? 'async ' : '';
+	const exportKeyword = isExport ? 'export ' : '';
+
 	const parametersText = functionExprNode.params.map(parameter => sourceCode.getText(parameter)).join(', ');
 	const bodyText = sourceCode.getText(functionExprNode.body);
 
-	const exportKeyword = isExport ? 'export ' : '';
-	return `${exportKeyword}function ${functionName}(${parametersText}) ${bodyText}`;
+	return `${exportKeyword}${asyncKeyword}function ${functionName}(${parametersText}) ${bodyText}`;
 }
 
 /**
- * Build a replacement for an anonymous top-level FunctionDeclaration.
+ * Build a replacement for an anonymous top-level FunctionDeclaration (including async).
  *
  * @param {import('eslint').SourceCode} sourceCode
  * @param {import('estree').FunctionDeclaration} node
  * @param {string} [funcName='defaultFunction']
+ * @param {boolean} [isExport=false]
  */
-function buildAnonymousFunctionDeclarationReplacement(sourceCode, node, functionName = 'defaultFunction') {
+function buildAnonymousFunctionDeclarationReplacement(sourceCode, node, functionName = 'defaultFunction', isExport = false) {
 	const originalText = sourceCode.getText(node);
+	const exportKeyword = isExport ? 'export ' : '';
+
+	let replaced = originalText;
+	const asyncFunctionRegex = /^\s*async\s+function\s*\(/;
+	const functionRegex = /^\s*function\s*\(/;
+
+	replaced = asyncFunctionRegex.test(replaced) ? replaced.replace(asyncFunctionRegex, `async function ${functionName}(`) : replaced.replace(functionRegex, `function ${functionName}(`);
 
-	const fixedText = originalText.replace(
-		/^(\s*function\s*)\(/,
-		`$1${functionName}(`,
-	);
-	return fixedText;
+	if (isExport && !replaced.trimStart().startsWith('export')) {
+		replaced = `${exportKeyword}${replaced}`;
+	}
+
+	return replaced;
 }
 
-/**
- * ESLint rule to enforce naming conventions for top-level functions.
- *
- * @param {Object} context - The rule context provided by ESLint.
- * @returns {Object} An object containing visitor methods for AST nodes.
- */
 function create(context) {
 	const sourceCode = context.getSourceCode();
 
@@ -129,7 +124,10 @@ function create(context) {
 							isExport,
 						);
 
-						return fixer.replaceText(grandParent.type === 'Program' ? declParent : grandParent, replacement);
+						return fixer.replaceText(
+							isExport ? grandParent : declParent,
+							replacement,
+						);
 					},
 				});
 			} else if (node.init.type === 'FunctionExpression') {
@@ -143,7 +141,10 @@ function create(context) {
 							sourceCode,
 							isExport,
 						);
-						return fixer.replaceText(grandParent.type === 'Program' ? declParent : grandParent, replacement);
+						return fixer.replaceText(
+							isExport ? grandParent : declParent,
+							replacement,
+						);
 					},
 				});
 			}
@@ -156,7 +157,8 @@ function create(context) {
 
 			const parent = node.parent;
 
-			const isTopLevel = parent.type === 'Program'
+			const isTopLevel
+				= parent.type === 'Program'
 				|| parent.type === 'ExportNamedDeclaration'
 				|| parent.type === 'ExportDefaultDeclaration';
 
@@ -164,15 +166,24 @@ function create(context) {
 				return;
 			}
 
+			const isExport
+				= parent.type === 'ExportNamedDeclaration'
+				|| parent.type === 'ExportDefaultDeclaration';
+
 			context.report({
 				node,
 				message: 'Top-level anonymous function declarations must be named.',
 				fix(fixer) {
 					const newName = 'defaultFunction';
-					const replacement = buildAnonymousFunctionDeclarationReplacement(sourceCode, node, newName);
+					const replacement = buildAnonymousFunctionDeclarationReplacement(
+						sourceCode,
+						node,
+						newName,
+						isExport,
+					);
 
 					return fixer.replaceText(
-						parent.type === 'Program' ? node : parent,
+						isExport ? parent : node,
 						replacement,
 					);
 				},

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,
+};