eslint-plugin-th-rules 1.17.1 → 1.18.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.18.0](https://github.com/tomerh2001/eslint-plugin-th-rules/compare/v1.17.1...v1.18.0) (2026-01-05)
+
+
+### Features
+
+* add 'schemas-in-schemas-file' rule to enforce Zod schema declarations in dedicated files ([92b54a0](https://github.com/tomerh2001/eslint-plugin-th-rules/commit/92b54a0b9ca4197c4e92c268d7d0cf0f8efc83cf))
+
 ## [1.17.1](https://github.com/tomerh2001/eslint-plugin-th-rules/compare/v1.17.0...v1.17.1) (2026-01-05)
 
 

package/README.md

@@ -14,14 +14,15 @@ 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][] |    |
-| [styles-in-styles-file](docs/rules/styles-in-styles-file.md) | Require React-Native StyleSheet.create(...) to be placed in a .styles.ts/.styles.tsx file | ✅ ![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][] |    |
+| 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][] |    |
+| [schemas-in-schemas-file](docs/rules/schemas-in-schemas-file.md) | Require Zod schema declarations to be placed in a .schemas.ts file                     | ✅ ![badge-recommended-react][] ![badge-recommended-typescript][] |    |
+| [styles-in-styles-file](docs/rules/styles-in-styles-file.md)     | Require React-Native StyleSheet.create(...) to be placed in a .styles.ts file          | ✅ ![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/schemas-in-schemas-file.md

@@ -0,0 +1,168 @@
+# Require Zod schema declarations to be placed in a .schemas.ts file (`th-rules/schemas-in-schemas-file`)
+
+💼 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 that Zod schema **declarations** are defined in dedicated schema files (by default: `.schemas.ts` / `.schemas.tsx`), rather than inside implementation/component files.
+
+The intent is to keep business logic and UI code focused, while consolidating validation/contract definitions into a predictable location.
+
+## Rationale
+
+Keeping Zod schemas in dedicated files:
+- reduces noise in implementation files (especially components and services),
+- encourages reuse of validation contracts across the codebase,
+- improves review quality by keeping diffs focused (schema changes vs logic changes),
+- standardizes file layout in larger projects and monorepos.
+
+## What the rule reports
+
+The rule reports Zod “schema builder” calls (e.g. `z.object(...)`, `z.string()`, `z.enum(...)`, `z.coerce.number()`, etc.) in files that do **not** match one of the allowed suffixes.
+
+By default, it identifies Zod usage by tracking imports from `'zod'` (e.g. `import { z } from 'zod'`, `import { z as zod } from 'zod'`, `import * as zod from 'zod'`).
+
+## Examples
+
+### ❌ Incorrect
+
+```ts
+// ArticleCard.tsx
+import {z} from 'zod';
+
+const articleSchema = z.object({
+	id: z.string(),
+	title: z.string().min(1),
+});
+```
+
+```ts
+// user.ts
+import {z as zod} from 'zod';
+
+export const userSchema = zod.object({
+	email: zod.string().email(),
+});
+```
+
+### ✅ Correct
+
+```ts
+// ArticleCard.schemas.ts
+import {z} from 'zod';
+
+export const articleSchema = z.object({
+	id: z.string(),
+	title: z.string().min(1),
+});
+```
+
+```ts
+// ArticleCard.tsx
+import {articleSchema} from './ArticleCard.schemas';
+
+export function ArticleCard() {
+	// articleSchema is used here (validation, inference, etc.)
+	return null;
+}
+```
+
+### Allowed usage (always allowed)
+
+Using schemas and type inference is allowed anywhere:
+
+```ts
+import type {z} from 'zod';
+import {articleSchema} from './ArticleCard.schemas';
+
+export type Article = z.infer&lt;typeof articleSchema&gt;;
+```
+
+## Options
+
+&lt;!-- begin auto-generated rule options list --&gt;
+
+| Name               | Type     |
+| :----------------- | :------- |
+| `allowedSuffixes`  | String[] |
+| `allowInTests`     | Boolean  |
+| `onlyWhenAssigned` | Boolean  |
+
+&lt;!-- end auto-generated rule options list --&gt;
+
+### `allowedSuffixes`
+
+An array of filename suffixes that are allowed to contain Zod schema declarations.
+
+Default:
+- `.schemas.ts`
+- `.schemas.tsx`
+
+Example:
+
+```json
+{
+  "rules": {
+    "th-rules/schemas-in-schemas-file": ["error", {
+      "allowedSuffixes": [".schemas.ts", ".schemas.tsx", ".validation.ts"]
+    }]
+  }
+}
+```
+
+### `allowInTests`
+
+When set to `true`, the rule allows Zod schema declarations in common test file patterns (e.g. `*.test.ts`, `*.spec.ts`, `*.test.tsx`, `*.spec.tsx`).
+
+Default: `false`
+
+Example:
+
+```json
+{
+  "rules": {
+    "th-rules/schemas-in-schemas-file": ["error", {
+      "allowInTests": true
+    }]
+  }
+}
+```
+
+### `onlyWhenAssigned`
+
+When set to `true`, the rule reports only Zod schema builder calls that are assigned to a variable (or assigned via `=`), for example:
+
+```ts
+const userSchema = z.object({ ... });
+userSchema = z.object({ ... });
+```
+
+If set to `false` (default), the rule reports any Zod schema builder call found in a non-allowed file, including inline schemas:
+
+```ts
+foo(z.object({ ... }));
+```
+
+Default: `false`
+
+Example:
+
+```json
+{
+  "rules": {
+    "th-rules/schemas-in-schemas-file": ["error", {
+      "onlyWhenAssigned": true
+    }]
+  }
+}
+```
+
+## Notes
+
+- This rule is filename-based; it enforces a convention rather than performing semantic analysis.
+- The rule does not auto-fix, as moving schemas across files safely (and updating imports) is not generally safe to automate.
+- If you define Zod builders through wrappers (e.g. `createSchema(...)` that internally calls Zod), this rule will not detect those unless extended to match your helper patterns.

package/docs/rules/styles-in-styles-file.md

@@ -1,11 +1,10 @@
-<pre>
-# Require React-Native StyleSheet.create(...) to be placed in a .styles.ts/.styles.tsx file (`th-rules/styles-in-styles-file`)
+# Require React-Native StyleSheet.create(...) to be placed in a .styles.ts file (`th-rules/styles-in-styles-file`)
 
 💼 This rule is enabled in the following configs: ✅ `recommended`, `recommended-react`, `recommended-typescript`.
 
 <!-- end auto-generated rule header -->
 
-This rule enforces that React-Native stylesheet declarations created via `StyleSheet.create(...)` live in a dedicated styles file, typically ending with `.styles.ts` or `.styles.tsx`.
+This rule enforces that React-Native stylesheet declarations created via `StyleSheet.create(...)` live in a dedicated styles file, typically ending with `.styles.ts`.
 
 In practice, this prevents implementation/component files from containing large style objects, and encourages consistent separation of concerns.
 
@@ -19,7 +18,7 @@ Keeping styles in dedicated files:
 
 ## What the rule reports
 
-The rule reports any `StyleSheet.create(...)` call in files whose names do **not** match one of the allowed suffixes (by default, `.styles.ts` and `.styles.tsx`).
+The rule reports any `StyleSheet.create(...)` call in files whose names do **not** match one of the allowed suffixes (by default, `.styles.ts`).
 
 Optionally, it can also report `StyleSheet.compose(...)` calls.
 
@@ -100,7 +99,6 @@ An array of filename suffixes that are allowed to contain `StyleSheet.create(...
 
 Default:
 - `.styles.ts`
-- `.styles.tsx`
 
 Example:
 
@@ -108,7 +106,7 @@ Example:
 {
   "rules": {
     "th-rules/styles-in-styles-file": ["error", {
-      "allowedSuffixes": [".styles.ts", ".styles.tsx", ".native-styles.ts"]
+      "allowedSuffixes": [".styles.ts", ".native-styles.ts"]
     }]
   }
 }
@@ -139,4 +137,3 @@ Example:
   - other styling systems (e.g., styled-components, Tamagui, Emotion),
   - calls to other `StyleSheet.*` helpers (e.g., `flatten`, `hairlineWidth`).
 - The rule is filename-based. If ESLint is invoked with `<input>` (stdin), the rule will treat it as not being an allowed styles file.
-</pre>

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

@@ -1,4 +1,3 @@
-<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`.
@@ -109,4 +108,3 @@ This can be helpful in codebases that rely on runtime enums while still wanting
 - 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.17.1",
+  "version": "1.18.0",
   "description": "A List of custom ESLint rules created by Tomer Horowitz",
   "keywords": [
     "eslint",

package/src/index.js

@@ -20,6 +20,7 @@ const configs = {
 			'th-rules/no-comments': 'error',
 			'th-rules/top-level-functions': 'error',
 			'th-rules/styles-in-styles-file': 'error',
+			'th-rules/schemas-in-schemas-file': 'error',
 			'th-rules/types-in-dts': 'error',
 			'unicorn/prefer-module': 'warn',
 			'unicorn/filename-case': 'off',

package/src/rules/schemas-in-schemas-file.js

@@ -0,0 +1,191 @@
+const meta = {
+	type: 'problem',
+	docs: {
+		description: 'Require Zod schema declarations to be placed in a .schemas.ts file',
+		category: 'Stylistic Issues',
+		recommended: false,
+		url: 'https://github.com/tomerh2001/eslint-plugin-th-rules/blob/main/docs/rules/schemas-in-schemas-file.md',
+	},
+	schema: [
+		{
+			type: 'object',
+			properties: {
+				allowedSuffixes: {
+					type: 'array',
+					items: {type: 'string', minLength: 1},
+					minItems: 1,
+				},
+				/**
+				 * If true, only report when the Zod call is assigned to a variable
+				 * (e.g. const userSchema = z.object(...)).
+				 * If false, report any Zod schema-building call expression.
+				 */
+				onlyWhenAssigned: {type: 'boolean'},
+
+				/**
+				 * If true, allow Zod calls inside *.test.* / *.spec.* files.
+				 */
+				allowInTests: {type: 'boolean'},
+			},
+			additionalProperties: false,
+		},
+	],
+	messages: {
+		moveSchema:
+			'Zod schemas must be defined in a dedicated schemas file ({{suffixes}}).',
+	},
+};
+
+function create(context) {
+	const options = context.options?.[0] ?? {};
+	const allowedSuffixes = options.allowedSuffixes ?? ['.schemas.ts'];
+	const onlyWhenAssigned = Boolean(options.onlyWhenAssigned);
+	const allowInTests = Boolean(options.allowInTests);
+
+	/** @type {Set<string>} */
+	const zodIdentifiers = new Set();
+
+	function filenameAllowed(filename) {
+		if (!filename || filename === '<input>') {
+			return false;
+		}
+
+		if (allowInTests
+			&& /\.(test|spec)\.[jt]sx?$/.test(filename)) {
+			return true;
+		}
+
+		return allowedSuffixes.some(suffix => filename.endsWith(suffix));
+	}
+
+	function isZodModuleImport(node) {
+		return node?.source?.type === 'Literal' && node.source.value === 'zod';
+	}
+
+	function collectZodIdentifiersFromImport(node) {
+		if (!isZodModuleImport(node)) {
+			return;
+		}
+
+		for (const spec of node.specifiers ?? []) {
+			if (spec.type === 'ImportSpecifier') {
+				const imported = spec.imported;
+				const local = spec.local;
+
+				if (imported?.type === 'Identifier' && imported.name === 'z' && local?.type === 'Identifier') {
+					zodIdentifiers.add(local.name);
+				}
+			}
+
+			if (spec.type === 'ImportNamespaceSpecifier' && spec.local?.type === 'Identifier') {
+				zodIdentifiers.add(spec.local.name);
+			}
+		}
+	}
+
+	function isZodBuilderCall(node) {
+		const callee = node?.callee;
+		if (!callee || callee.type !== 'MemberExpression') {
+			return false;
+		}
+
+		if (callee.computed) {
+			return false;
+		}
+
+		const object = callee.object;
+		const property = callee.property;
+
+		if (object?.type !== 'Identifier') {
+			return false;
+		}
+
+		if (!zodIdentifiers.has(object.name)) {
+			return false;
+		}
+
+		return property?.type === 'Identifier';
+	}
+
+	function isZodChainedBuilderCall(node) {
+		const callee = node?.callee;
+		if (!callee || callee.type !== 'MemberExpression') {
+			return false;
+		}
+
+		if (callee.computed) {
+			return false;
+		}
+
+		let current = callee.object;
+		while (current && current.type === 'MemberExpression' && !current.computed) {
+			current = current.object;
+		}
+
+		return current?.type === 'Identifier' && zodIdentifiers.has(current.name);
+	}
+
+	function getAssignmentTargetName(callNode) {
+		const p = callNode.parent;
+
+		if (p?.type === 'VariableDeclarator') {
+			if (p.id?.type === 'Identifier') {
+				return p.id.name;
+			}
+
+			return null;
+		}
+
+		if (p?.type === 'AssignmentExpression') {
+			if (p.left?.type === 'Identifier') {
+				return p.left.name;
+			}
+
+			return null;
+		}
+
+		return null;
+	}
+
+	function report(node) {
+		const filename = context.getFilename();
+		if (filenameAllowed(filename)) {
+			return;
+		}
+
+		const targetName = getAssignmentTargetName(node);
+		if (onlyWhenAssigned && !targetName) {
+			return;
+		}
+
+		const target = targetName ? ` "${targetName}"` : '';
+
+		context.report({
+			node,
+			messageId: 'moveSchema',
+			data: {
+				filename,
+				suffixes: allowedSuffixes.join(' or '),
+				target,
+			},
+		});
+	}
+
+	return {
+		ImportDeclaration(node) {
+			collectZodIdentifiersFromImport(node);
+		},
+
+		CallExpression(node) {
+			if (zodIdentifiers.size === 0) {
+				return;
+			}
+
+			if (isZodBuilderCall(node) || isZodChainedBuilderCall(node)) {
+				report(node);
+			}
+		},
+	};
+}
+
+module.exports = {meta, create};

package/src/rules/styles-in-styles-file.js

@@ -1,7 +1,7 @@
 const meta = {
 	type: 'problem',
 	docs: {
-		description: 'Require React-Native StyleSheet.create(...) to be placed in a .styles.ts/.styles.tsx file',
+		description: 'Require React-Native StyleSheet.create(...) to be placed in a .styles.ts file',
 		category: 'Stylistic Issues',
 		recommended: false,
 		url: 'https://github.com/tomerh2001/eslint-plugin-th-rules/blob/main/docs/rules/styles-in-styles-file.md',
@@ -22,13 +22,13 @@ const meta = {
 	],
 	messages: {
 		moveStyles:
-			'React-Native styles{{target}} must be defined in a dedicated styles file ({{suffixes}}). Current file: "{{filename}}".',
+			'React-Native styles must be defined in a dedicated styles file ({{suffixes}}).',
 	},
 };
 
 function create(context) {
 	const options = context.options?.[0] ?? {};
-	const allowedSuffixes = options.allowedSuffixes ?? ['.styles.ts', '.styles.tsx'];
+	const allowedSuffixes = options.allowedSuffixes ?? ['.styles.ts'];
 	const includeCompose = Boolean(options.includeCompose);
 
 	function isAllowedStyleFile(filename) {

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

@@ -22,7 +22,7 @@ const meta = {
 	],
 	messages: {
 		moveToDts:
-			'Type declarations must be moved to a .d.ts file (for example "{{filename}}.d.ts").',
+			'Type declarations must be moved to a .d.ts file.',
 	},
 };