# criteo/eslint-plugin-criteo architecture

> Architecture diagram of the GitHub repository criteo/eslint-plugin-criteo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/criteo/eslint-plugin-criteo
- Repository: https://github.com/criteo/eslint-plugin-criteo

## Overview

##### Project type and purpose
- This is an open-source ESLint plugin (named `eslint-plugin-criteo`).
- Its purpose is to provide a curated set of linting **rules**, **configs**, and a **helper** (`buildConfig`) for Angular (and soon React) projects, enforcing Criteo’s coding conventions.

##### File structure
- Top level:
- `package.json` / `package-lock.json` (metadata, dependencies)
- `.gitignore`, `.npmrc`, `LICENSE`, `CHANGELOG.md` (standard project files)
- `lib/` (the heart of the plugin)
- In `lib/`:
- `index.js` – plugin entry point, exports `rules`, `configs`, and the `buildConfig` helper
- `configs/` – JavaScript modules defining named configurations (`recommended`, `recommendedAngularApp`, etc.)
- `rules/` – individual rule implementations (`cypress-no-force.js`, `filename.js`, etc.)
- `utils.js` – shared utilities used by rule implementations

##### README for additional insights
- Lists the configurations exposed (`recommendedAngularApp`, `recommendedAngularTemplate`, `recommended`, etc.)
- Describes how the `buildConfig()` helper flattens and merges nested configurations
- Details each custom rule’s intent and configuration options
- Shows usage patterns for importing the plugin in an ESLint config

##### Main components
a. **ESLint Core Engine**
- Represents the ESLint CLI or API that loads plugins and runs lint passes.
b. **Plugin Entry Point (`lib/index.js`)**
- Exports:
- **Rules Registry** – maps rule names to rule definitions from `lib/rules/`
- **Configs Registry** – maps config names to rule-sets from `lib/configs/`
- **buildConfig Helper** – function to merge and override configs
c. **Rule Implementation Modules (`lib/rules/*.js`)**
- Each module exports a Rule object that ESLint invokes for AST checks.
- Use shared functions from `lib/utils.js`.
d. **Config Definition Modules (`lib/configs/*.js`)**
- Arrays of ESLint settings, enabling internal and external rules.
- Some configs import external plugin configs (e.g., `@typescript-eslint`, `angular-eslint`).
e. **Utility Module (`lib/utils.js`)**
- Provides helper functions for rule authors (e.g., file-name parsing).
f. **External Plugins & Shared Rules**
- External dependencies listed in `package.json` (e.g., `@typescript-eslint`, `eslint-plugin-cypress`).
- Config modules include or extend external rule sets.
g. **Consumer Project**
- An Angular (or React) codebase that installs this plugin and references its exported configs in its ESLint pipeline.

##### Relationships and interactions
- **ESLint Core** → loads → **Plugin Entry Point**
- **Plugin Entry** → exposes → **Rules Registry** & **Configs Registry** ↔ uses ↔ **Rule Modules**, **Config Modules**, **Utils**
- **Config Modules** → reference → **External Plugin Configs / Rules**
- **Consumer Project** → invokes → **ESLint Core** → which applies → **Selected Plugin Config** → running → **Rules**

##### Architectural patterns and design principles
- **Modularization:** each rule and config lives in its own file to isolate concerns.
- **Registry Pattern:** index.js formats exports as two registries (`rules` and `configs`) for ESLint to consume.
- **Extensibility:** `buildConfig()` helper allows merging and overriding default settings.
- **Dependency Injection:** config modules declare external plugins centrally, so updates are localized.

##### Diagramming recommendations
- Core Plugin (entry, utils)
- Rules
- Configs
- External Plugins
- Consumer Project / ESLint Core
- From ESLint Core → Plugin Entry
- From Plugin Entry → Rules & Configs
- From Configs → External Plugins
- From Consumer Project → ESLint Core

- The plugin’s internal structure (modules and registries)
- How it ties into ESLint’s plugin architecture
- Where custom logic and policy definitions reside
- How external rule sets are incorporated
- The consumer’s role in invoking the plugin through ESLint

## Diagram (Mermaid)

```mermaid
flowchart TB
    Consumer["Consumer Project"]:::consumer
    ESLintCore["ESLint Core Engine"]:::engine
    Consumer -->|"invokes"| ESLintCore
    ESLintCore -->|"loads plugin"| PluginEntry

    subgraph "Core Plugin"
        direction TB
        PluginEntry["Plugin Entry"]:::core
        BuildConfig["buildConfig()"]:::core
        RulesRegistry["Rules Registry"]:::rules
        ConfigsRegistry["Configs Registry"]:::configs
        Utils["Utils Module (lib/utils.js)"]:::core

        PluginEntry --> RulesRegistry
        PluginEntry --> ConfigsRegistry
        PluginEntry --> BuildConfig
        RulesRegistry --> Utils
        ConfigsRegistry --> Utils

        subgraph "Rules"
            direction TB
            RNF["cypress-no-force"]:::rule
            RFM["filename-match-export"]:::rule
            RF["filename"]:::rule
            IF["independent-folders"]:::rule
            NCD["ngx-component-display"]:::rule
            NSC["ngx-no-styles-in-component"]:::rule
            NSAL["ngxs-selector-array-length"]:::rule
            NIE["no-indexed-access-on-enums"]:::rule
            NNSD["no-ngxs-select-decorator"]:::rule
            NNDUC["no-null-undefined-comparison"]:::rule
            NSA["no-spreading-accumulators"]:::rule
            NTW["no-todo-without-ticket"]:::rule
            PRD["prefer-readonly-decorators"]:::rule
            UD["until-destroy"]:::rule

            RulesRegistry --> RNF
            RulesRegistry --> RFM
            RulesRegistry --> RF
            RulesRegistry --> IF
            RulesRegistry --> NCD
            RulesRegistry --> NSC
            RulesRegistry --> NSAL
            RulesRegistry --> NIE
            RulesRegistry --> NNSD
            RulesRegistry --> NNDUC
            RulesRegistry --> NSA
            RulesRegistry --> NTW
            RulesRegistry --> PRD
            RulesRegistry --> UD
        end

        subgraph "Configs"
            direction TB
            CONF1["recommended"]:::config
            CONF2["recommended-angular"]:::config
            CONF3["recommended-angular-template"]:::config
            CONF4["criteo-setup-angular-app"]:::config

            ConfigsRegistry --> CONF1
            ConfigsRegistry --> CONF2
            ConfigsRegistry --> CONF3
            ConfigsRegistry --> CONF4

            CONF1 --> ExternalTS
            CONF2 --> ExternalTS
            CONF2 --> ExternalAngular
            CONF3 --> ExternalTS
            CONF3 --> ExternalAngular
            CONF4 --> ExternalCypress
        end

        click PluginEntry "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/index.js"
        click BuildConfig "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/index.js"
        click RulesRegistry "https://github.com/criteo/eslint-plugin-criteo/tree/master/lib/rules/"
        click RNF "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/cypress-no-force.js"
        click RFM "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/filename-match-export.js"
        click RF "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/filename.js"
        click IF "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/independent-folders.js"
        click NCD "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/ngx-component-display.js"
        click NSC "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/ngx-no-styles-in-component.js"
        click NSAL "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/ngxs-selector-array-length.js"
        click NIE "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/no-indexed-access-on-enums.js"
        click NNSD "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/no-ngxs-select-decorator.js"
        click NNDUC "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/no-null-undefined-comparison.js"
        click NSA "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/no-spreading-accumulators.js"
        click NTW "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/no-todo-without-ticket.js"
        click PRD "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/prefer-readonly-decorators.js"
        click UD "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/rules/until-destroy.js"
        click ConfigsRegistry "https://github.com/criteo/eslint-plugin-criteo/tree/master/lib/configs/"
        click CONF1 "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/configs/recommended.js"
        click CONF2 "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/configs/recommended-angular.js"
        click CONF3 "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/configs/recommended-angular-template.js"
        click CONF4 "https://github.com/criteo/eslint-plugin-criteo/blob/master/lib/configs/criteo-setup-angular-app.js"
    end

    subgraph "External Plugins"
        direction TB
        ExternalTS[( @typescript-eslint )]:::external
        ExternalAngular[( @angular-eslint )]:::external
        ExternalCypress[( eslint-plugin-cypress )]:::external
    end

    classDef consumer fill:#E3F2FD,stroke:#90CAF9
    classDef engine fill:#FFE0B2,stroke:#FB8C00
    classDef core fill:#C8E6C9,stroke:#388E3C
    classDef rules fill:#EF9A9A,stroke:#C62828
    classDef rule fill:#FFCDD2,stroke:#E53935
    classDef configs fill:#B39DDB,stroke:#6A1B9A
    classDef config fill:#D1C4E9,stroke:#7B1FA2
    classDef external fill:#B2DFDB,stroke:#00796B
```
