@ovh-ux/manager-static-analysis-kit 0.2.0

package/src/adapters/eslint/README.md

@@ -0,0 +1,317 @@
+# ESLint Static Analysis Kit — Plugin Overview & Rule Index
+
+This document provides a full breakdown of all ESLint plugins, rules, and conventions used in the `@ovh-ux/manager-static-analysis-kit`.
+
+---
+
+## 📦 Package Overview
+
+```json
+{
+  "name": "@ovh-ux/manager-static-analysis-kit",
+  "version": "x.x.x",
+  "description": "A modular, extensible, and future-ready toolkit for defining, adapting, and sharing static analysis rules across projects in the `manager` monorepo."
+}
+```
+
+---
+
+## 🔌 Installed ESLint Plugins
+
+### 🎯 Core ESLint
+
+| Package         | Purpose                                |
+|----------------|----------------------------------------|
+| `eslint`        | Core linting engine                    |
+| `@eslint/js`    | Base rule set for JS/TS                |
+| `@eslint/css`   | CSS linting support                    |
+
+---
+
+### 🧱 Structure & Naming Enforcement
+
+| Plugin                          | Description |
+|----------------------------------|-------------|
+| `eslint-plugin-check-file`      | File and folder naming rules |
+| `eslint-import-resolver-typescript` | Type-aware path resolution for imports |
+
+---
+
+### 🧩 Code Style & Formatting
+
+| Plugin / Tool                      | Description |
+|------------------------------------|-------------|
+| `prettier`                         | Formatter |
+| `eslint-plugin-prettier`           | Runs Prettier as a lint rule |
+| `eslint-config-prettier`           | Disables ESLint rules conflicting with Prettier |
+| `@trivago/prettier-plugin-sort-imports` | Sorts imports automatically |
+| `prettier-plugin-tailwindcss`      | Sorts Tailwind classes |
+
+---
+
+### 🧠 Language & Syntax
+
+| Plugin                             | Description |
+|-----------------------------------|-------------|
+| `@typescript-eslint/eslint-plugin`| TypeScript lint rules |
+| `@typescript-eslint/parser`       | TS parser for ESLint |
+| `@typescript-eslint/utils`        | TypeScript rule tooling |
+| `@types/eslint`, `@types/node`    | Type support |
+
+---
+
+### ⚛️ React & JSX
+
+| Plugin                             | Description |
+|-----------------------------------|-------------|
+| `eslint-plugin-react`             | React best practices |
+| `eslint-plugin-react-hooks`       | React Hook rules |
+| `eslint-plugin-jsx-a11y`          | JSX accessibility |
+| `eslint-plugin-storybook`         | Storybook-specific rules |
+
+---
+
+### 💨 Tailwind CSS
+
+| Plugin                             | Description |
+|-----------------------------------|-------------|
+| `eslint-plugin-tailwindcss`       | Tailwind usage validation |
+| `@types/eslint-plugin-tailwindcss`| Types for Tailwind plugin |
+| `tailwind-csstree`                | Tailwind CSS AST analysis |
+
+---
+
+### 🔍 HTML & Templates
+
+| Plugin                             | Description |
+|-----------------------------------|-------------|
+| `@html-eslint/eslint-plugin`      | HTML rules |
+| `@html-eslint/parser`             | HTML parsing support |
+
+---
+
+### 🧪 Testing
+
+| Plugin                             | Description |
+|-----------------------------------|-------------|
+| `@vitest/eslint-plugin`           | Vitest rules |
+
+---
+
+### 🧶 TanStack Query
+
+| Plugin                             | Description |
+|-----------------------------------|-------------|
+| `@tanstack/eslint-plugin-query`   | Best practices for `tanstack-query` |
+
+---
+
+## 📁 Rule Modules
+
+Available in `src/adapters/eslint/rules/`:
+
+| Module                         | Purpose                          |
+|--------------------------------|----------------------------------|
+| `eslint-a11y.ts`               | Accessibility rules              |
+| `eslint-complexity.ts`         | Code complexity constraints      |
+| `eslint-css.ts`                | Linting for stylesheets          |
+| `eslint-html.ts`               | HTML linting rules               |
+| `eslint-imports.ts`            | Import rules and conventions     |
+| `eslint-javascript.ts`         | Generic JavaScript rules         |
+| `eslint-naming-conventions.ts` | Folder/file naming enforcement   |
+| `eslint-prettier.ts`           | Prettier integration             |
+| `eslint-react.ts`              | React conventions and structure  |
+| `eslint-storybook.ts`          | Storybook-specific lint rules    |
+| `eslint-tailwind-jsx.ts`       | Tailwind inside JSX              |
+| `eslint-tanstack.ts`           | Linting for TanStack Query usage|
+| `eslint-tests.ts`              | Testing rules (e.g., Vitest)     |
+| `eslint-typescript.ts`         | TypeScript-specific rules        |
+
+---
+
+## 📤 Package Export Map
+
+```json
+"exports": {
+  ".": "./dist/code-analysis.js",
+  "./eslint/config": "./dist/adapters/eslint/config/eslint-shared-config.js",
+  "./eslint/storybook": "./dist/adapters/eslint/rules/eslint-storybook.js",
+  "./eslint/a11y": "./dist/adapters/eslint/rules/eslint-a11y.js",
+  "./eslint/complexity": "./dist/adapters/eslint/rules/eslint-complexity.js",
+  "./eslint/css": "./dist/adapters/eslint/rules/eslint-css.js",
+  "./eslint/html": "./dist/adapters/eslint/rules/eslint-html.js",
+  "./eslint/imports": "./dist/adapters/eslint/rules/eslint-imports.js",
+  "./eslint/javascript": "./dist/adapters/eslint/rules/eslint-javascript.js",
+  "./eslint/naming-conventions": "./dist/adapters/eslint/rules/eslint-naming-conventions.js",
+  "./eslint/prettier": "./dist/adapters/eslint/rules/eslint-prettier.js",
+  "./eslint/react": "./dist/adapters/eslint/rules/eslint-react.js",
+  "./eslint/tailwind-jsx": "./dist/adapters/eslint/rules/eslint-tailwind-jsx.js",
+  "./eslint/tanstack": "./dist/adapters/eslint/rules/eslint-tanstack.js",
+  "./eslint/tests": "./dist/adapters/eslint/rules/eslint-tests.js",
+  "./eslint/typescript": "./dist/adapters/eslint/rules/eslint-typescript.js"
+}
+```
+
+---
+
+## 🧪 Custom CLI
+
+```json
+"bin": {
+  "manager-lint": "./bin/lint.js"
+}
+```
+
+To lint your codebase:
+
+```bash
+yarn manager-lint path/to/package
+```
+
+---
+
+## 🔧 Usage Options
+
+### ✅ Option 1: Full Shared Config
+
+```ts
+import { eslintSharedConfig } from '@ovh-ux/manager-static-analysis-kit';
+
+export default eslintSharedConfig;
+```
+
+### 🔀 Option 2: Progressive Adoption
+
+```ts
+import { javascriptEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/javascript';
+import { typescriptEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/typescript';
+import { reactEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/react';
+import { prettierEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/prettier';
+import { a11yEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/a11y';
+import { complexityJsxTsxConfig, complexityTsJsConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/complexity';
+import { htmlEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/html';
+import { cssEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/css';
+import { tailwindJsxConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/tailwind-jsx';
+import { tanStackQueryEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/tanstack';
+import { importEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/imports';
+import { checkFileEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/naming-conventions';
+import { vitestEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/tests';
+
+export default [
+  javascriptEslintConfig,
+  typescriptEslintConfig,
+  reactEslintConfig,
+  a11yEslintConfig,
+  htmlEslintConfig,
+  cssEslintConfig,
+  tailwindJsxConfig,
+  tanStackQueryEslintConfig,
+  ...importEslintConfig,
+  ...checkFileEslintConfig,
+  vitestEslintConfig,
+  prettierEslintConfig,
+  complexityJsxTsxConfig,
+  complexityTsJsConfig,
+];
+```
+
+### ❌ Option 3: Override or Disable Rules
+
+```ts
+import { typescriptEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/typescript';
+
+export default [
+  {
+    ...typescriptEslintConfig,
+    rules: {
+      ...typescriptEslintConfig.rules,
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/await-thenable': 'off'
+    },
+  },
+];
+```
+
+**Disable all rules:**
+
+```ts
+import { typescriptEslintConfig } from '@ovh-ux/manager-static-analysis-kit/eslint/typescript';
+
+export default [
+  {
+    ...typescriptEslintConfig,
+    rules: {},
+  },
+];
+```
+
+---
+
+## 🚀 CLI Support
+
+With Flat Config enabled, use the following script definitions:
+
+```json
+{
+  "scripts": {
+    "lint": "manager-lint --config eslint.config.mjs ./src",
+    "lint:fix": "manager-lint --fix --config eslint.config.mjs ./src"
+  }
+}
+```
+
+---
+
+## 📁 File Naming Conventions
+
+| Purpose        | Pattern                         | Format               |
+|----------------|---------------------------------|----------------------|
+| Component      | `*.component.tsx`               | `PASCAL_CASE`        |
+| Hook           | `use*.ts`, `use*.tsx`           | `CAMEL_CASE`         |
+| Hook Test      | `use*.spec.ts`, `use*.test.ts`  | `CAMEL_CASE`         |
+| Test           | `*.spec.tsx`, `*.test.tsx`      | `PASCAL_CASE`        |
+| Constants      | `*.constants.ts`                | `PASCAL_CASE`        |
+| Types          | `*.type.ts`, `*.interface.ts`   | `PASCAL_CASE`        |
+| Translations   | `Messages_en_GB.json`           | `SCREAMING_SNAKE_CASE` |
+| Styles         | `*.css`, `*.scss`               | `KEBAB_CASE`         |
+| Configs        | `*.config.ts`, `vite.config.ts` | `KEBAB_CASE`         |
+
+---
+
+## 🧼 React Best Practices
+
+### 📛 One Component per File
+
+We enforce **one React component per file** to encourage modularity and readability:
+
+```json
+"react/no-multi-comp": ["error", { "ignoreStateless": false }]
+```
+
+---
+
+## 📊 Complexity Rules Summary
+
+| Rule                      | Target                | Limit                  |
+|---------------------------|------------------------|-------------------------|
+| `max-depth`              | Any block             | 4 levels                |
+| `max-params`             | Function parameters   | 4 parameters            |
+| `max-nested-callbacks`   | Callbacks             | 3 levels                |
+| `complexity`             | Cyclomatic complexity | 10–15 (context-based)   |
+| `max-lines`              | Per file              | 300 lines               |
+| `max-lines-per-function` | Function body         | 50–80 lines             |
+
+---
+
+## 📎 Related Links
+
+- [TypeScript Config Guide](./README_tsconfig_static_analysis_kit.md)
+- [Monorepo Guidelines](https://github.com/ovh/manager/tree/master/packages/manager)
+
+---
+
+## 📜 License
+
+BSD-3-Clause — © OVH SAS

package/src/adapters/eslint/config/eslint-shared-config.ts

@@ -0,0 +1,60 @@
+import { Linter } from 'eslint';
+
+import { a11yEslintConfig } from '../rules/eslint-a11y';
+import { complexityJsxTsxConfig, complexityTsJsConfig } from '../rules/eslint-complexity';
+import { cssEslintConfig } from '../rules/eslint-css';
+import { htmlEslintConfig } from '../rules/eslint-html';
+import { importEslintConfig } from '../rules/eslint-imports';
+import { javascriptEslintConfig } from '../rules/eslint-javascript';
+import { checkFileEslintConfig } from '../rules/eslint-naming-conventions';
+import { prettierEslintConfig } from '../rules/eslint-prettier';
+import { reactEslintConfig } from '../rules/eslint-react';
+import { tailwindJsxConfig } from '../rules/eslint-tailwind-jsx';
+import { tanStackQueryEslintConfig } from '../rules/eslint-tanstack';
+import { vitestEslintConfig } from '../rules/eslint-tests';
+import { typescriptEslintConfig } from '../rules/eslint-typescript';
+
+/**
+ * Shared ESLint Flat Config aggregation for the OVH Manager codebase.
+ *
+ * This includes linting rules for:
+ * - Core web languages (HTML, CSS, JS, TS)
+ * - Popular tools and frameworks (React, Tailwind, Vitest, TanStack Query)
+ * - Code structure, complexity, and formatting
+ * - File naming and import conventions
+ *
+ * You may use this full config or import specific ones individually.
+ *
+ * @example
+ * ```ts
+ * import { eslintSharedConfig } from '@ovh-ux/manager-static-analysis-kit';
+ * export default eslintSharedConfig;
+ * ```
+ */
+export const eslintSharedConfig: Linter.FlatConfig[] = [
+  // Core language support
+  htmlEslintConfig,
+  javascriptEslintConfig,
+  typescriptEslintConfig,
+  cssEslintConfig,
+
+  // Static analysis extensions
+  ...importEslintConfig, // JS/TS import rules
+  tailwindJsxConfig, // Tailwind CSS linting
+  a11yEslintConfig, // Accessibility
+
+  // Frameworks & Libraries
+  reactEslintConfig,
+  tanStackQueryEslintConfig,
+
+  // Testing and complexity constraints
+  vitestEslintConfig,
+  complexityJsxTsxConfig,
+  complexityTsJsConfig,
+
+  // Formatter (should go last to avoid conflict)
+  prettierEslintConfig,
+
+  // Structural constraints (e.g., file/folder naming)
+  ...checkFileEslintConfig,
+];

package/src/adapters/eslint/rules/eslint-a11y.ts

@@ -0,0 +1,30 @@
+import { Linter } from 'eslint';
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+import { allModules } from '../../../configs/file-globs-config';
+
+/**
+ * Accessibility ESLint configuration using `eslint-plugin-jsx-a11y`.
+ *
+ * This configuration applies recommended accessibility rules for JSX,
+ * and is scoped to all JavaScript and TypeScript modules, including
+ * React and modern module formats.
+ *
+ * @see https://www.npmjs.com/package/eslint-plugin-jsx-a11y
+ */
+export const a11yEslintConfig: Linter.FlatConfig = {
+  files: [allModules],
+  plugins: {
+    'jsx-a11y': jsxA11y,
+  },
+  languageOptions: {
+    parserOptions: {
+      ecmaFeatures: {
+        jsx: true,
+      },
+    },
+  },
+  rules: {
+    ...jsxA11y.flatConfigs.recommended.rules,
+  },
+};

package/src/adapters/eslint/rules/eslint-complexity.ts

@@ -0,0 +1,87 @@
+import { Linter } from 'eslint';
+
+import { complexityRules } from '../../../configs/complexity-config';
+import { jsTsFiles, jsxTsxFiles } from '../../../configs/file-globs-config';
+
+/**
+ * Shared complexity rules applied across all file types
+ */
+const sharedComplexityRules: Linter.RulesRecord = {
+  /** Maximum nesting depth of blocks */
+  'max-depth': ['warn', complexityRules.maxDepth],
+
+  /** Maximum number of function parameters */
+  'max-params': ['warn', complexityRules.maxParams],
+
+  /** Maximum number of nested callbacks */
+  'max-nested-callbacks': ['warn', complexityRules.maxCallbacks],
+};
+
+/**
+ * Complexity rules for TSX/JSX files
+ */
+export const complexityJsxTsxConfig: Linter.FlatConfig = {
+  files: [jsxTsxFiles],
+  rules: {
+    ...sharedComplexityRules,
+
+    /** Cyclomatic complexity */
+    complexity: ['warn', complexityRules.statements.tsxJsx],
+
+    /** Max lines per file */
+    'max-lines': [
+      'warn',
+      {
+        max: complexityRules.maxLines,
+        skipBlankLines: true,
+        skipComments: true,
+      },
+    ],
+
+    /** Max lines per function */
+    'max-lines-per-function': [
+      'warn',
+      {
+        max: complexityRules.linesPerFunction.tsxJsx,
+        skipBlankLines: true,
+        skipComments: true,
+        IIFEs: true,
+      },
+    ],
+  },
+};
+
+/**
+ * Complexity rules for TS/JS files
+ */
+export const complexityTsJsConfig: Linter.FlatConfig = {
+  files: [jsTsFiles],
+  ignores: [jsxTsxFiles],
+  rules: {
+    ...sharedComplexityRules,
+
+    /** Cyclomatic complexity */
+    complexity: ['warn', complexityRules.statements.tsJs],
+
+    /** Max lines per file */
+    'max-lines': [
+      'warn',
+      {
+        max: complexityRules.maxLines,
+        skipBlankLines: true,
+        skipComments: true,
+      },
+    ],
+
+    /** Max lines per function */
+    'max-lines-per-function': [
+      'warn',
+      {
+        max: complexityRules.linesPerFunction.tsJs,
+        skipBlankLines: true,
+        skipComments: true,
+        IIFEs: true,
+      },
+    ],
+  },
+};

package/src/adapters/eslint/rules/eslint-css.ts

@@ -0,0 +1,35 @@
+import css from '@eslint/css';
+import { ESLint, Linter } from 'eslint';
+import { tailwind4 } from 'tailwind-csstree';
+
+import { cssFiles } from '../../../configs/file-globs-config';
+
+type ExtendedFlatConfig = Linter.FlatConfig & {
+  language?: string;
+  languageOptions?: Record<string, unknown>;
+};
+
+/**
+ * ESLint configuration for validating CSS files, including Tailwind CSS syntax.
+ *
+ * Uses `@eslint/css` plugin with `tailwind-csstree` custom parser to support Tailwind-specific syntax.
+ * Ensures clean and valid CSS, while integrating seamlessly into modern component-based workflows.
+ *
+ * Applies only to `.css` files.
+ *
+ * @see https://github.com/eslint/css?tab=readme-ov-file#rules
+ * @see https://github.com/francoismassart/tailwind-csstree
+ */
+export const cssEslintConfig: ExtendedFlatConfig = {
+  files: [cssFiles],
+  language: 'css/css',
+  languageOptions: {
+    customSyntax: tailwind4,
+  },
+  plugins: {
+    css: css as unknown as ESLint.Plugin,
+  },
+  rules: {
+    ...css.configs.recommended.rules,
+  },
+};

package/src/adapters/eslint/rules/eslint-html.ts

@@ -0,0 +1,32 @@
+import htmlPlugin from '@html-eslint/eslint-plugin';
+import htmlParser from '@html-eslint/parser';
+import { ESLint, Linter } from 'eslint';
+
+import { htmlFiles } from '../../../configs/file-globs-config';
+
+/**
+ * ESLint Flat Config for linting HTML files using `@html-eslint`.
+ *
+ * This configuration applies HTML-specific best practices and ensures
+ * semantic correctness, accessibility, and proper formatting of HTML documents.
+ *
+ * It uses the custom parser `@html-eslint/parser` to interpret HTML syntax
+ * and the recommended rule set from `@html-eslint/eslint-plugin`.
+ *
+ * Applies only to `.html` files.
+ *
+ * @see https://html-eslint.org/docs/rules
+ */
+export const htmlEslintConfig: Linter.FlatConfig = {
+  files: [htmlFiles],
+  ignores: [],
+  plugins: {
+    '@html-eslint': htmlPlugin as unknown as ESLint.Plugin,
+  },
+  languageOptions: {
+    parser: htmlParser,
+  },
+  rules: {
+    ...htmlPlugin.configs['flat/recommended'].rules,
+  },
+};

package/src/adapters/eslint/rules/eslint-imports.ts

@@ -0,0 +1,84 @@
+import js from '@eslint/js';
+import { Linter } from 'eslint';
+import importPlugin from 'eslint-plugin-import';
+import tsEslint from 'typescript-eslint';
+
+import { jsFiles, tsFiles } from '../../../configs/file-globs-config';
+
+/**
+ * Shared import-related ESLint rules applied across both JavaScript and TypeScript.
+ *
+ * Includes cycle detection, discourages dynamic `require`, and disallows usage of core Node.js modules directly.
+ */
+const sharedImportRules: Record<string, Linter.RuleEntry | undefined> = {
+  ...importPlugin.flatConfigs.recommended.rules,
+  'import/no-cycle': [
+    'error',
+    {
+      maxDepth: Infinity,
+      ignoreExternal: false,
+      allowUnsafeDynamicCyclicDependency: false,
+      disableScc: false,
+    },
+  ],
+  'import/no-dynamic-require': 'warn',
+  'import/no-nodejs-modules': 'warn',
+};
+
+/**
+ * JavaScript-specific import rules.
+ * Enables base `no-unused-vars` since TypeScript version is not in use.
+ */
+const jsImportRules: Record<string, Linter.RuleEntry | undefined> = {
+  ...sharedImportRules,
+  'no-unused-vars': 'warn',
+};
+
+/**
+ * TypeScript-specific import rules.
+ * Disables base `no-unused-vars` in favor of the TypeScript-aware variant from `@typescript-eslint`.
+ */
+const tsImportRules: Record<string, Linter.RuleEntry | undefined> = {
+  ...sharedImportRules,
+  'no-unused-vars': 'off',
+  '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+};
+
+/**
+ * ESLint Flat Config for managing import conventions, cycles, and unused rules
+ * for both JavaScript and TypeScript environments.
+ *
+ * - Uses `eslint-plugin-import` for best practices
+ * - Applies proper rules per language
+ * - Configures import resolver for TS files
+ *
+ * @see https://github.com/import-js/eslint-plugin-import
+ */
+export const importEslintConfig: Linter.FlatConfig[] = [
+  // JavaScript configuration block
+  js.configs.recommended,
+  importPlugin.flatConfigs.recommended,
+  {
+    files: [jsFiles],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    rules: jsImportRules,
+  },
+
+  // TypeScript configuration block
+  ...tsEslint.config({
+    files: [tsFiles],
+    extends: [importPlugin.flatConfigs.recommended, importPlugin.flatConfigs.typescript],
+    rules: tsImportRules,
+    settings: {
+      'import/resolver': {
+        typescript: {
+          alwaysTryTypes: true,
+        },
+        node: true,
+      },
+    },
+  }),
+];

package/src/adapters/eslint/rules/eslint-javascript.ts

@@ -0,0 +1,27 @@
+import js from '@eslint/js';
+import { Linter } from 'eslint';
+
+import { jsFilesLoose } from '../../../configs/file-globs-config';
+
+/**
+ * ESLint Flat Config for standard JavaScript files.
+ *
+ * Applies:
+ * - ESLint's built-in recommended rules via `@eslint/js`
+ * - Supports both `.js` and `.jsx` files (loose JS pattern)
+ * - Configured for ECMAScript Modules (`sourceType: 'module'`)
+ *
+ * @see https://eslint.org/docs/latest/rules/
+ */
+export const javascriptEslintConfig: Linter.FlatConfig = {
+  files: [jsFilesLoose],
+  ignores: [],
+  languageOptions: {
+    ...js.languageOptions,
+    sourceType: 'module',
+  },
+  plugins: js.plugins,
+  rules: {
+    ...js.configs.recommended.rules,
+  },
+};