@zimbra/eslint-config 0.0.1

package/RULES.md

@@ -0,0 +1,387 @@
+# RULES
+
+This file is generated from `src/rules/` and `src/rules/custom-rules/`. It lists the rule modules and explains, in simple language, what each rule or setting does. Keep this file up to date when rules change.
+
+---
+
+## **src/rules/automation.js**
+
+Purpose: Rules for automation scripts (CI, build tools, scripts). These relax some checks that are noisy or unnecessary in short scripts.
+
+Rules and what they do:
+
+- `prettier/prettier`: off — do not run Prettier formatting checks in automation blocks.
+- `prefer-const`: off — allow `let` even when a variable could be `const` (useful in scripting patterns).
+- `require-atomic-updates`: off — do not warn about certain async update race conditions.
+- `guard-for-in`: off — do not require `hasOwnProperty` checks in `for..in` loops.
+- `react/jsx-no-useless-fragment`: off — allow fragments even if they look redundant.
+- `lines-around-comment`: off — disable rules enforcing blank lines around comments.
+- `no-unexpected-multiline`: off — do not warn for some ambiguous multi-line expressions.
+- `no-spaced-func`: off — allow `function` call spacing (compatibility choice).
+- `new-cap`: off — do not require constructor names to be capitalized.
+- `no-undef-init`: off — allow `var x = undefined` style patterns.
+- `no-shadow`: off — allow variable shadowing in automation scripts.
+- `no-case-declarations`: off — allow declarations inside `switch` cases.
+- `no-constant-binary-expression`: off — do not warn for constant expressions in binary operators.
+- `semi`: ["error", "always"] — require semicolons at the end of statements.
+
+Source: `src/rules/automation.js`
+
+---
+
+## **src/rules/i18n.js**
+
+Purpose: Checks for localization (i18n) JSON files and i18n usage in templates.
+
+Rules and what they do:
+
+- `i18n-json/sorted-keys` — enforces a stable, custom key order in locale JSON files (uses `scripts/intl/lint-custom-sort.cjs`). This keeps translations sorted in a consistent order.
+- `i18n-json/identical-keys` — ensures locale files have the same keys as the primary language file (defaults to `src/intl/en_US.json`).
+- `preact-i18n/no-missing-template-field` — reports when a template expects a field that's not provided.
+- `preact-i18n/no-text-as-attribute` — prevents raw text used directly in attributes instead of using translations.
+- `preact-i18n/no-text-as-children` — prevents raw text as children in i18n-aware components (ignores small punctuation-only strings).
+- `preact-i18n/no-unknown-key` — reports when a translation key used in code is not found in the locale files.
+
+Notes:
+- Use `ESLINT_INTL_PATH` environment variable to change where locale files are read from.
+
+Source: `src/rules/i18n.js`
+
+---
+
+## **src/rules/import.js**
+
+Purpose: Small adjustments for import-related checks.
+
+Rules and what they do:
+
+- `import/no-unresolved`: off — do not treat unresolved imports as errors (useful when bundlers or custom resolvers are in use).
+- `import/no-named-as-default`: off — allow using a named export as default in some patterns.
+
+Source: `src/rules/import.js`
+
+---
+
+## **src/rules/parser.js**
+
+Purpose: Central parser configuration used for TypeScript-enabled linting blocks.
+
+What it sets:
+
+- `parser`: `@typescript-eslint/parser` — enables TypeScript-aware parsing.
+- `sourceType`: `module` — treat files as ES modules.
+- `ecmaVersion`: `latest` — allow modern JavaScript syntax.
+- `parserOptions.requireConfigFile`: false — parser won't require a tsconfig for basic parsing.
+- `parserOptions.ecmaFeatures.jsx`: true — enable JSX parsing.
+
+Use this parser settings block when enabling TypeScript rules or type-aware checks.
+
+Source: `src/rules/parser.js`
+
+---
+
+## **src/rules/prettier.js**
+
+Purpose: Configure Prettier options surfaced through ESLint.
+
+Rule and options:
+
+- `prettier/prettier`: `error` — formatting issues are reported as ESLint errors. Options set:
+  - `singleQuote: true` — prefer single quotes.
+  - `printWidth: 100` — wrap lines at 100 characters.
+  - `trailingComma: 'none'` — do not add trailing commas.
+  - `arrowParens: 'avoid'` — omit parentheses for single-arg arrow functions where possible.
+
+Note: Consumer projects should install `prettier` to get fixes via `eslint --fix`.
+
+Source: `src/rules/prettier.js`
+
+---
+
+## **src/rules/react-hooks.js**
+
+Purpose: Adjust React Hooks plugin rules for Zimbra code style.
+
+Rules and what they do:
+
+- `react-hooks/refs`: off — disables the `refs` rule from the react-hooks plugin.
+- `react-hooks/immutability`: off — disables immutability checks for hooks-related code.
+
+These are turned off to avoid false positives or to match our patterns across codebases.
+
+Source: `src/rules/react-hooks.js`
+
+---
+
+## **src/rules/react.js**
+
+Purpose: React-specific rule adjustments for modern code (often TypeScript-based).
+
+Rules and what they do:
+
+- `react/prop-types`: off — do not require PropTypes (TypeScript or other systems handle type checks).
+- `react/no-unknown-property`: off — allow some non-standard attributes (project-specific usage).
+- `react/react-in-jsx-scope`: off — no longer required with newer JSX transforms.
+- `react/jsx-key`: off — JSX key warnings are disabled (teams may use different patterns).
+
+Source: `src/rules/react.js`
+
+---
+
+## **src/rules/style.js**
+
+Purpose: Style and code-shape rules that affect common JavaScript patterns.
+
+Rules and what they do:
+
+- `no-undef`: off — do not report undefined variables here (TypeScript or other checks may handle this).
+- `no-unsafe-optional-chaining`: off — allow some optional chaining patterns that would otherwise be flagged.
+- `no-empty`: off — allow empty blocks in some cases.
+- `no-empty-pattern`: off — allow empty destructuring patterns.
+- `no-unused-vars`: `['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true, caughtErrors: 'none' }]` — report unused variables, but ignore some common patterns (e.g., rest siblings).
+
+Source: `src/rules/style.js`
+
+---
+
+## **src/rules/typescript.js**
+
+Purpose: Turn off some `@typescript-eslint` rules that are noisy by default across many projects.
+
+Rules and what they do:
+
+- `@typescript-eslint/no-explicit-any`: off — allow `any` types in code without lint errors.
+- `@typescript-eslint/no-empty-object-type`: off — allow `{} as type` patterns.
+- `@typescript-eslint/no-unused-expressions`: off — allow certain unused expressions.
+- `@typescript-eslint/no-unsafe-function-type`: off — do not error on some unsafe function types.
+- `@typescript-eslint/no-unused-vars`: off — TypeScript-based unused-var handling may be preferred or tightened per-project.
+
+Note: Projects that want stricter TypeScript rules should override these settings in their local config.
+
+Source: `src/rules/typescript.js`
+
+---
+
+## **src/rules/custom-rules/custom-rules.js**
+
+Purpose: Enables custom (project-specific) rules located in `src/rules/custom-rules/`.
+
+Key setting:
+
+- `custom/no-direct-memoize`: `error` — enable the rule that blocks direct memoize imports.
+
+Source: `src/rules/custom-rules/custom-rules.js`
+
+---
+
+## **src/rules/custom-rules/no-direct-memoize.js**
+
+Purpose: A custom rule that prevents importing certain memoize helpers directly.
+
+What it enforces:
+
+- Disallows imports of `es-toolkit/compat/memoize` and `es-toolkit/memoize`.
+- Reports an error and recommends using `createLRUMemoize` instead.
+
+Why: Centralizes use of a specific memoize implementation (LRU-based) and avoids inconsistent memoization helpers.
+
+Example that triggers the rule:
+
+```js
+import memoize from 'es-toolkit/memoize'; // ❌ triggers rule
+const x = memoize(fn);
+```
+
+Example that follows the rule:
+
+```js
+import { createLRUMemoize } from 'some-lru-helper'; // ✅ allowed
+const memo = createLRUMemoize(...);
+```
+
+Source: `src/rules/custom-rules/no-direct-memoize.js`
+
+# RULES
+
+This file was generated automatically from the source files under `src/rules/` and `src/rules/custom-rules/`. It summarizes the purpose and key settings for each rule/config module exported by the package. If you change rules in `src/rules`, regenerate this file or update it manually.
+
+---
+
+## **src/rules/automation.js**
+
+Purpose: Relax or adjust linting rules for automation and CI scripts. The automation rules turn off several stylistic and runtime checks that are commonly noisy in automation scripts and set a required semicolon style.
+
+Key settings (excerpt):
+
+- `prettier/prettier`: off
+- `prefer-const`: off
+- `require-atomic-updates`: off
+- `guard-for-in`: off
+- `semi`: ["error", "always"]
+
+Use when: applying lint rules to scripts used in CI, build tooling, or non-interactive environments where stricter runtime style checks may be unnecessary.
+
+Source: `src/rules/automation.js`
+
+---
+
+## **src/rules/i18n.js**
+
+Purpose: Provide i18n-related rules and configuration for both JSON locale files and Preact/Preact-i18n usage.
+
+What it contains:
+
+- `i18nJsonRules` — configuration for `eslint-plugin-i18n-json`, including a custom sort function (`scripts/intl/lint-custom-sort.cjs`) and reference to the primary language file (defaults to `src/intl/en_US.json` or overridden via `ESLINT_INTL_PATH`).
+- `i18nRules` — runtime/template checks for Preact i18n (e.g. `no-missing-template-field`, `no-text-as-attribute`).
+- `LANGUAGE_FILES_RELATIVE` — a list of supported language filename mappings included for reference.
+- `i18nTextComponents` — helper patterns used to identify text-containing components for i18n checks.
+
+Notes:
+
+- `ESLINT_INTL_PATH` env var can override the default locale path.
+- Useful for projects that validate JSON locale files and enforce i18n usage in templates.
+
+Source: `src/rules/i18n.js`
+
+---
+
+## **src/rules/import.js**
+
+Purpose: Minimal adjustments for `eslint-plugin-import` rules in this config.
+
+Key settings (excerpt):
+
+- `import/no-unresolved`: off
+- `import/no-named-as-default`: off
+
+Source: `src/rules/import.js`
+
+---
+
+## **src/rules/parser.js**
+
+Purpose: Centralized parser configuration for TypeScript-aware parsing.
+
+Key settings:
+
+- `parser`: `@typescript-eslint/parser`
+- `sourceType`: `module`
+- `ecmaVersion`: `latest`
+- `parserOptions.requireConfigFile`: false
+- `parserOptions.ecmaFeatures.jsx`: true
+
+Use when: enabling TypeScript rules or type-aware linting blocks.
+
+Source: `src/rules/parser.js`
+
+---
+
+## **src/rules/prettier.js**
+
+Purpose: Prettier integration settings exposed as an ESLint rule block.
+
+Key settings (excerpt):
+
+- `prettier/prettier`: `error` with options: `singleQuote: true`, `printWidth: 100`, `trailingComma: 'none'`, `arrowParens: 'avoid'`.
+
+This file configures Prettier rules so that formatting errors are surfaced by ESLint and can be fixed with `eslint --fix` when `prettier` and `eslint-plugin-prettier` are present.
+
+Source: `src/rules/prettier.js`
+
+---
+
+## **src/rules/react-hooks.js**
+
+Purpose: Adjust React Hooks-related rules. This config disables certain rules from `eslint-plugin-react-hooks` that are not desired across Zimbra codebases.
+
+Key settings:
+
+- `react-hooks/refs`: off
+- `react-hooks/immutability`: off
+
+Source: `src/rules/react-hooks.js`
+
+---
+
+## **src/rules/react.js**
+
+Purpose: React-specific rule adjustments. The config turns off prop-types and other rules that are unnecessary in modern TypeScript/React codebases or in projects that use other type systems.
+
+Key settings (excerpt):
+
+- `react/prop-types`: off
+- `react/no-unknown-property`: off
+- `react/react-in-jsx-scope`: off
+- `react/jsx-key`: off
+
+Source: `src/rules/react.js`
+
+---
+
+## **src/rules/style.js**
+
+Purpose: Style and basic code-shape rules. Controls undefined variables, empty patterns, and unused variable behavior.
+
+Key settings (excerpt):
+
+- `no-undef`: off
+- `no-empty`: off
+- `no-unused-vars`: `['error',{vars:'all',args:'after-used',ignoreRestSiblings:true,caughtErrors:'none'}]`
+
+Source: `src/rules/style.js`
+
+---
+
+## **src/rules/typescript.js**
+
+Purpose: TypeScript-focused rule overrides using `@typescript-eslint` plugin.
+
+Key settings (excerpt):
+
+- `@typescript-eslint/no-explicit-any`: off
+- `@typescript-eslint/no-unused-vars`: off
+- `@typescript-eslint/no-empty-object-type`: off
+
+These relax certain strict checks which may otherwise be noisy across the codebase; enable stronger checks by overriding in a project's local config if desired.
+
+Source: `src/rules/typescript.js`
+
+---
+
+## **src/rules/custom-rules/custom-rules.js**
+
+Purpose: Enable custom rules defined in `src/rules/custom-rules/`.
+
+Key setting:
+
+- `custom/no-direct-memoize`: `error`
+
+This file acts as a small wrapper to enable Zimbra-specific custom rules.
+
+Source: `src/rules/custom-rules/custom-rules.js`
+
+---
+
+## **src/rules/custom-rules/no-direct-memoize.js**
+
+Purpose: Custom lint rule that disallows direct imports of `es-toolkit/compat/memoize` and `es-toolkit/memoize` and instructs developers to use `createLRUMemoize` instead.
+
+Metadata from the rule (auto-extracted):
+
+- **Description**: Disallow direct import of es-toolkit/compat/memoize or es-toolkit/memoize; use createLRUMemoize
+- **Type**: problem
+- **Recommended**: true
+- **Message**: "Do not import es-toolkit/compat/memoize or es-toolkit/memoize; directly. Use 'createLRUMemoize' instead."
+
+Behavior summary:
+
+- Reports on ES module `ImportDeclaration` nodes when the source matches any disallowed module.
+- Reports on `require()` calls with the same disallowed modules.
+
+Source: `src/rules/custom-rules/no-direct-memoize.js`
+
+---
+
+How this file was generated
+
+This `RULES.md` was produced by extracting obvious descriptions, top-level settings, and JSDoc-like metadata from the rule/config source files. It is intended as a concise human-readable summary; for implementation details and exact rule shapes, refer to the original source files under `src/rules/`.

package/eslint.config.mjs

@@ -0,0 +1,5 @@
+import { coreJsConfig } from "./src/index.js";
+
+export default [
+  ...coreJsConfig
+];

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zimbra/eslint-config",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "ESLint configuration for Zimbra javascript projects.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./typescript": "./src/typescript.js"
+  },
+  "scripts": {
+    "lint": "eslint src",
+    "lint:fix": "npm run lint -- --fix"
+  },
+  "dependencies": {
+    "@eslint/compat": "^1.0.0",
+    "@eslint/js": "^9.37.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-i18n-json": "^4.0.1",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-mocha": "^10.2.0",
+    "eslint-plugin-preact-i18n": "^1.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-testcafe": "^0.2.1",
+    "typescript": "^5.9.3",
+    "@typescript-eslint/parser": "^8.48.1",
+    "globals": "^15.15.0",
+    "prettier": "^3.6.2"
+  },
+  "peerDependencies": {
+    "eslint": "^9.37.0",
+    "@typescript-eslint/eslint-plugin": "^8.50.1"
+  },
+  "peerDependenciesMeta": {
+    "@typescript-eslint/eslint-plugin": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.50.1"
+  }
+}

package/scripts/intl/lint-custom-sort.cjs

@@ -0,0 +1,8 @@
+module.exports = translations => {
+	return Object.keys(translations).sort((keyA, keyB) => {
+		return keyA.localeCompare(keyB, undefined, {
+			numeric: true,
+			sensitivity: 'base'
+		});
+	});
+};

package/src/configs/automation-config.js

@@ -0,0 +1,16 @@
+import testcafePlugin from 'eslint-plugin-testcafe';
+import { automationRules } from '../rules/automation.js';
+
+export default [
+	{
+		files: ['test/**/*.{js,jsx,mjs,cjs}', 'tests/**/*.{js,jsx,mjs,cjs}'],
+		ignores: ['**/node_modules/*', '**/dist/*', '**/build/*'],
+		plugins: {
+			testcafePlugin: testcafePlugin
+		},
+		rules: {
+			...testcafePlugin.configs.recommended.rules,
+			...automationRules
+		}
+	}
+];

package/src/configs/core-js-config.js

@@ -0,0 +1,79 @@
+import eslint from '@eslint/js';
+import { fixupPluginRules } from '@eslint/compat';
+import globals from 'globals';
+import path from 'path';
+
+import prettierConfig from 'eslint-config-prettier';
+import pluginPrettier from 'eslint-plugin-prettier';
+import pluginMocha from 'eslint-plugin-mocha';
+import pluginPreactI18n from 'eslint-plugin-preact-i18n';
+import pluginReact from 'eslint-plugin-react';
+import pluginReactHooks from 'eslint-plugin-react-hooks';
+import importPlugin from 'eslint-plugin-import';
+
+import styleRules from '../rules/style.js';
+import reactRules from '../rules/react.js';
+import reactHooksRules from '../rules/react-hooks.js';
+import importRules from '../rules/import.js';
+import { i18nRules, LANGUAGE_FILES_RELATIVE, i18nTextComponents } from '../rules/i18n.js';
+import prettierRules from '../rules/prettier.js';
+import parserConfig from '../rules/parser.js';
+
+const coreRules = {
+	...styleRules,
+	...reactRules,
+	...reactHooksRules,
+	...importRules,
+	...prettierRules,
+	...i18nRules
+};
+
+const intlPath = process.env.ESLINT_INTL_PATH ?? 'src/intl';
+
+const languageFilesAbsolute = LANGUAGE_FILES_RELATIVE.map(entry => ({
+	name: entry.name,
+	path: path.join(intlPath, entry.filename)
+}));
+
+export default [
+	{
+		files: ['**/*.{js,jsx,mjs,cjs}'],
+
+		ignores: ['**/node_modules/*', '**/dist/*', '**/build/*', '**/*.graphql', '**/*.gql'],
+
+		languageOptions: {
+			...parserConfig,
+			globals: {
+				...globals.browser,
+				...globals.node
+			}
+		},
+
+		plugins: {
+			react: pluginReact,
+			'react-hooks': pluginReactHooks,
+			mocha: fixupPluginRules(pluginMocha),
+			prettier: pluginPrettier,
+			import: importPlugin,
+			// TODO: Upgrade `pluginPreactI18n` to a modern version to ensure compatibility with current tooling and React/Preact best practices
+			'preact-i18n': fixupPluginRules(pluginPreactI18n)
+		},
+
+		rules: {
+			...eslint.configs.recommended.rules,
+			...prettierConfig.rules,
+			...pluginReact.configs.recommended.rules,
+			...pluginReactHooks.configs.recommended.rules,
+			...importPlugin.configs.recommended.rules,
+			...coreRules
+		},
+
+		settings: {
+			react: { pragma: 'createElement', version: '16.3' },
+			'preact-i18n': {
+				languageFiles: languageFilesAbsolute,
+				textComponents: i18nTextComponents
+			}
+		}
+	}
+];

package/src/configs/custom-config.js

@@ -0,0 +1,19 @@
+import customRules from '../rules/custom-rules/custom-rules.js';
+import noDirectMemoize from '../rules/custom-rules/no-direct-memoize.js';
+
+export default [
+	{
+		files: ['**/*.{js,jsx,mjs,cjs}'],
+		ignores: ['**/node_modules/*', '**/dist/*', '**/build/*'],
+		plugins: {
+			custom: {
+				rules: {
+					'no-direct-memoize': noDirectMemoize
+				}
+			}
+		},
+		rules: {
+			...customRules
+		}
+	}
+];

package/src/configs/locale-json-config.js

@@ -0,0 +1,20 @@
+import pluginI18nJson from 'eslint-plugin-i18n-json';
+import { i18nJsonRules } from '../rules/i18n.js';
+
+export default [
+	{
+		files: ['**/*.json'],
+		ignores: ['**/node_modules/*', '**/dist/*', '**/build/*'],
+		plugins: {
+			'i18n-json': pluginI18nJson
+		},
+		processor: {
+			meta: { name: '.json' },
+			...pluginI18nJson.processors['.json']
+		},
+		rules: {
+			...pluginI18nJson.configs.recommended.rules,
+			...i18nJsonRules
+		}
+	}
+];

package/src/configs/ts-eslint-config.js

@@ -0,0 +1,33 @@
+import pluginPrettier from 'eslint-plugin-prettier';
+import tsParser from '@typescript-eslint/parser';
+import pluginTypescript from '@typescript-eslint/eslint-plugin';
+import importPlugin from 'eslint-plugin-import';
+import typescriptRules from '../rules/typescript.js';
+import prettierRules from '../rules/prettier.js';
+
+export default [
+	{
+		ignores: ['**/dist/**', '**/build/**', '**/node_modules/**', '**/*.d.ts']
+	},
+	{
+		files: ['**/*.{ts,tsx}'],
+		languageOptions: {
+			parser: tsParser,
+			sourceType: 'module',
+			ecmaVersion: 'latest',
+			parserOptions: {
+				project: true
+			}
+		},
+		plugins: {
+			'@typescript-eslint': pluginTypescript,
+			import: importPlugin,
+			prettier: pluginPrettier
+		},
+		rules: {
+			...pluginTypescript.configs.recommended.rules,
+			...prettierRules,
+			...typescriptRules
+		}
+	}
+];

package/src/index.js

@@ -0,0 +1,6 @@
+import automationConfig from './configs/automation-config.js';
+import localeJsonConfig from './configs/locale-json-config.js';
+import coreJsConfig from './configs/core-js-config.js';
+import customConfig from './configs/custom-config.js';
+
+export { coreJsConfig, localeJsonConfig, automationConfig, customConfig };

package/src/rules/automation.js

@@ -0,0 +1,16 @@
+export const automationRules = {
+	'prettier/prettier': 'off',
+	'prefer-const': 'off',
+	'require-atomic-updates': 'off',
+	'guard-for-in': 'off',
+	'react/jsx-no-useless-fragment': 'off',
+	'lines-around-comment': 'off',
+	'no-unexpected-multiline': 'off',
+	'no-spaced-func': 'off',
+	'new-cap': 'off',
+	'no-undef-init': 'off',
+	'no-shadow': 'off',
+	'no-case-declarations': 'off',
+	'no-constant-binary-expression': 'off',
+	semi: ['error', 'always']
+};

package/src/rules/custom-rules/custom-rules.js

@@ -0,0 +1,3 @@
+export default {
+	'custom/no-direct-memoize': 'error'
+};