# lint-staged/lint-staged architecture

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

- Interactive diagram: https://gitdiagram.com/lint-staged/lint-staged
- Repository: https://github.com/lint-staged/lint-staged

## Overview

##### Project Overview and Main Purpose
- This project is a Node.js command-line tool that integrates with Git hooks (typically via Husky) to run code quality tasks on only the staged files. It supports various configuration file types (JSON, YAML, JS, TypeScript, etc.) and uses Git operations (such as stashing) to preserve and roll back changes on errors.
- The tool is used in the developer workflow to ensure that only correctly formatted or linted code is committed.

##### File Structure for Architectural Clues
- Top-Level Directories and Files:
- The “bin” directory contains executable scripts (for example, the main CLI entry point).
- The “lib” directory includes the core modules (e.g., modules for chunking files, executing Git commands, resolving configuration, running tasks, etc.). This clearly indicates a separation of concerns in the implementation.
- The “test” directory with subdirectories for unit, integration, and end-to-end tests reinforces that the project is well modularized.
- Configuration and setup files (Husky hooks in “.husky”, eslint/prettier configuration, and various GitHub workflow files) show integration with both Git and CI/CD environments.
- The README explains usage details and typical configuration flows (such as how the CLI is invoked in a Git pre-commit hook) as well as examples for configuring tasks.

##### Main Components
a. CLI Layer (Entry Point):
- “bin/lint-staged.js” as the starting point when a Git commit is processed via a Husky pre-commit hook.
b. Input / Git Integration:
- A component that “listens” to Git events (triggered by Git hooks). This component is responsible for reading staged files and handling Git stashing (backup and restore).
c. Configuration Loader:
- This component reads and resolves configuration settings from various sources (such as package.json’s “lint-staged” field, various “.lintstagedrc” files, and JS/TS config files).
- It should include the processes for dynamic import (“dynamicImport.js”) and resolving configuration (“loadConfig.js”, “resolveConfig.js”).
d. Task Manager / Runner:
- This part of the system maps file glob patterns (via micromatch) to user-configured command-line tasks.
- It manages the execution tasks, including support for running multiple commands (array of commands) and handling concurrency (serial/parallel) as specified by the CLI options.
- It also deals with safety precautions such as detecting if a task undoes all changes and then aborting the commit.
e. Command Executor:
- A component that accepts the prepared commands (with the filtered staged files) and executes them using underlying libraries (like “execa” for running external commands) and prints output through renderers (listr2).
- This component ensures that task errors are captured and reported in the CLI feedback.
f. Output / Logging:
- A logging and debug component for handling standard output and error messages (as indicated by the debug and verbose flags).
- Optionally, include a separate module for testing that verifies the correctness of each module and the system’s integration (as is evidenced by the “test” directory).

##### Illustrating Relationships and Flow
- Begin at the top with the Git pre-commit hook triggering the CLI entry point.
- From the Git Integration module, pass the list of staged files to the Configuration Loader module.
- The Configuration Loader parses the configuration from various sources and produces a set of rules (mapping globs to commands).
- Feed these rules into the Task Manager, which further breaks down the staged files (using magicians like micromatch) and prepares task commands.
- Finally, feedback from the Command Executor flows back (including successes, failures, and possible restoration steps via the Git Integration module) to the CLI layer.

##### Design Patterns and Technologies
- That the project design follows modular design principles and separation of concerns (distinct modules for configuration, task execution, and Git operations).
- That the CLI tool is built upon Node.js and leverages external libraries such as “execa”, “micromatch”, and “listr2” for command execution and output rendering.
- Concurrency management as an architectural principle; show how tasks can be executed concurrently or serially based on provided flags.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLIEntry["CLI Entry (lint-staged)"]
    end

    subgraph "Git Hook/Integration Module"
        ExecGit["execGit.js"]
        ResolveGitRepo["resolveGitRepo.js"]
        GetStagedFiles["getStagedFiles.js"]
        GitWorkflow["gitWorkflow.js"]
    end

    subgraph "Configuration Loader"
        LoadConfig["loadConfig.js"]
        ResolveConfig["resolveConfig.js"]
        DynamicImport["dynamicImport.js"]
        ConfigFiles["configFiles.js"]
    end

    subgraph "Task Manager/Runner"
        GenerateTasks["generateTasks.js"]
        MakeCmdTasks["makeCmdTasks.js"]
    end

    subgraph "Command Executor"
        RunAll["runAll.js"]
    end

    subgraph "Output / Logging"
        GetRenderer["getRenderer.js"]
        Figures["figures.js"]
        PrintTaskOutput["printTaskOutput.js"]
    end

    subgraph "Test Infrastructure"
        TestDir["Tests"]
    end

    %% Flow Connections
    CLIEntry -->|"triggers"| ExecGit
    ExecGit -->|"reads-Git-files"| GetStagedFiles
    GetStagedFiles -->|"identifies-repo"| ResolveGitRepo
    ResolveGitRepo --> GitWorkflow
    GitWorkflow -->|"passes-staged-files"| LoadConfig
    LoadConfig -->|"loads-config"| ResolveConfig
    ResolveConfig --> DynamicImport
    DynamicImport --> ConfigFiles
    ConfigFiles -->|"provides-config-rules"| GenerateTasks
    GenerateTasks -->|"maps-patterns"| MakeCmdTasks
    MakeCmdTasks -->|"creates-command-tasks"| RunAll
    RunAll -->|"executes-commands"| GetRenderer
    GetRenderer -->|"generates-output"| Figures
    Figures -->|"formats-output"| PrintTaskOutput
    RunAll -->|"reports-result"| GitWorkflow
    PrintTaskOutput -->|"logs-final-outcome"| CLIEntry
    TestDir -.->|"optional-testing"| CLIEntry

    %% Click Events
    click CLIEntry "https://github.com/lint-staged/lint-staged/blob/main/bin/lint-staged.js"
    click ExecGit "https://github.com/lint-staged/lint-staged/blob/main/lib/execGit.js"
    click ResolveGitRepo "https://github.com/lint-staged/lint-staged/blob/main/lib/resolveGitRepo.js"
    click GetStagedFiles "https://github.com/lint-staged/lint-staged/blob/main/lib/getStagedFiles.js"
    click GitWorkflow "https://github.com/lint-staged/lint-staged/blob/main/lib/gitWorkflow.js"
    click LoadConfig "https://github.com/lint-staged/lint-staged/blob/main/lib/loadConfig.js"
    click ResolveConfig "https://github.com/lint-staged/lint-staged/blob/main/lib/resolveConfig.js"
    click DynamicImport "https://github.com/lint-staged/lint-staged/blob/main/lib/dynamicImport.js"
    click ConfigFiles "https://github.com/lint-staged/lint-staged/blob/main/lib/configFiles.js"
    click GenerateTasks "https://github.com/lint-staged/lint-staged/blob/main/lib/generateTasks.js"
    click MakeCmdTasks "https://github.com/lint-staged/lint-staged/blob/main/lib/makeCmdTasks.js"
    click RunAll "https://github.com/lint-staged/lint-staged/blob/main/lib/runAll.js"
    click GetRenderer "https://github.com/lint-staged/lint-staged/blob/main/lib/getRenderer.js"
    click Figures "https://github.com/lint-staged/lint-staged/blob/main/lib/figures.js"
    click PrintTaskOutput "https://github.com/lint-staged/lint-staged/blob/main/lib/printTaskOutput.js"
    click TestDir "https://github.com/lint-staged/lint-staged/tree/main/test"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef git fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef config fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef task fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef executor fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef logging fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef test fill:#FFA07A,stroke:#333,stroke-width:2px;

    class CLIEntry cli;
    class ExecGit,ResolveGitRepo,GetStagedFiles,GitWorkflow git;
    class LoadConfig,ResolveConfig,DynamicImport,ConfigFiles config;
    class GenerateTasks,MakeCmdTasks task;
    class RunAll executor;
    class GetRenderer,Figures,PrintTaskOutput logging;
    class TestDir test;
```
