# joosthart/pre-commit-hook-mypy architecture

> Architecture diagram of the GitHub repository joosthart/pre-commit-hook-mypy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joosthart/pre-commit-hook-mypy
- Repository: https://github.com/joosthart/pre-commit-hook-mypy

## Overview

##### Project type and purpose
- **Type**: A command-line tool / Git pre-commit hook written in Python.
- **Purpose**: When a user runs `git commit`, the hook invokes mypy on all files to resolve imports but only reports errors for the files being committed.

##### File structure
- Top-level directories:
- `src/pre_commit_hook_mypy/` contains the implementation.
- `tests/` holds unit tests.
- `docs/` illustrates usage examples.
- Config and packaging files: `pyproject.toml`, `setup.py`, `requirements-dev.txt`, GitHub workflow, pre-commit templates.
- Key modules under `src/pre_commit_hook_mypy/`:
- `cli.py` – entry point for the hook.
- `mypy_committed.py` – logic to detect committed files, invoke mypy, filter output.
- Deployment: packaged to PyPI, installed via `pip install -e .`, referenced in `.pre-commit-config.yaml`.

##### Extract insights from the README
- The hook steps:
1. Committed Python files.
2. Run mypy on entire codebase (for proper import resolution).
3. Filter mypy’s output to errors in the committed files only.
4. Fail the commit if errors remain.
- Configuration options mirror the standard mypy pre-commit hook.

##### Main components
a. **External Systems**
- Git (user triggers `git commit`)
- Pre-commit framework (invokes the hook)
- mypy tool (external type checker)
b. **Internal Components**
- CLI module (`cli.py`) – invoked by pre-commit
- File detection submodule (in `mypy_committed.py`) – queries Git for a list of staged `.py` files
- Mypy invocation submodule – spawns a subprocess running `mypy` on the codebase
- Output filter submodule – parses mypy stdout/stderr, filters messages to only those whose file path matches the staged files list
- Exit handler – returns success (0) or failure (non-zero) to pre-commit
c. **Configuration Layer**
- `.pre-commit-config.yaml` (defines hook ID, args, additional dependencies)
- `pyproject.toml` / `setup.py` (packaging metadata)

##### Relationships and data flow
1. User runs `git commit`.
2. Pre-commit framework intercepts the commit and invokes the **pre_commit_hook_mypy** CLI.
3. **CLI module** calls the **file detection** logic to get the list of staged Python files from Git.
4. CLI then calls the **mypy invocation** logic with the full codebase path (ensuring correct module resolution).
5. mypy runs and emits errors/warnings for all checked files.
6. **Output filter** processes mypy’s output, keeping only errors related to the staged files.
7. **Exit handler** determines if filtered errors exist:
– If yes, it exits with a nonzero status → commit aborted.
– If no, it exits with zero → commit proceeds.

##### Architectural patterns and design principles
- Single-Responsibility: each submodule does one thing (detect files, call mypy, filter output).
- Modularity: CLI vs. core logic (`mypy_committed.py`) separated for testability.
- External dependency isolation: invoking mypy as a subprocess rather than embedding it.
- Extensibility: CLI accepts arbitrary mypy args and additional dependencies via pre-commit config.

##### Technologies and frameworks
- Python 3.x
- click or argparse (depending on implementation in `cli.py`)
- subprocess or similar for external calls
- pytest for tests (`tests/` directory)
- pre-commit framework for hook orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        Git["Git"]:::external
        PreCommit["Pre-commit Framework"]:::external
        MypyTool["mypy Tool"]:::external
    end

    %% Internal Components
    subgraph "Internal Components"
        CLI["CLI Module"]:::internal
        FileDetector["File Detection Submodule"]:::internal
        MypyInvoker["Mypy Invocation Submodule"]:::internal
        OutputFilter["Output Filter Submodule"]:::internal
        ExitHandler["Exit Handler"]:::internal
    end

    %% Configuration & Documentation
    subgraph "Configuration & Docs"
        PreCommitConfig[".pre-commit-hooks.yaml"]:::config
        Packaging1["pyproject.toml"]:::config
        Packaging2["setup.py"]:::config
        DevReqs["requirements-dev.txt"]:::config
        README["README.md"]:::docs
        DocExamplesConfig["docs/examples/pre-commit-config.yaml"]:::docs
        DocExamplesCode["docs/examples/"]:::docs
    end

    %% Test Harness
    subgraph "Test Harness"
        Conftest["tests/conftest.py"]:::test
        TestCore["tests/test_mypy_committed.py"]:::test
    end

    %% Data Flow
    Git -->|"git commit"| PreCommit
    PreCommit -->|invokes| CLI
    CLI -->|gets staged files| FileDetector
    FileDetector -->|queries staged .py files| Git
    CLI -->|runs full codebase| MypyInvoker
    MypyInvoker -->|spawns subprocess| MypyTool
    MypyTool -->|stdout/stderr| OutputFilter
    OutputFilter -->|filtered errors| CLI
    CLI -->|exit code| ExitHandler
    ExitHandler -->|returns status| PreCommit

    %% Test relationships
    Conftest -->|mocks| FileDetector
    Conftest -->|mocks| MypyInvoker
    TestCore -->|tests logic in| FileDetector
    TestCore -->|tests logic in| OutputFilter

    %% Click Events
    click CLI "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/src/pre_commit_hook_mypy/cli.py"
    click FileDetector "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/src/pre_commit_hook_mypy/mypy_committed.py"
    click MypyInvoker "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/src/pre_commit_hook_mypy/mypy_committed.py"
    click OutputFilter "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/src/pre_commit_hook_mypy/mypy_committed.py"
    click ExitHandler "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/src/pre_commit_hook_mypy/cli.py"
    click PreCommitConfig "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/.pre-commit-hooks.yaml"
    click Packaging1 "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/pyproject.toml"
    click Packaging2 "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/setup.py"
    click DevReqs "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/requirements-dev.txt"
    click Conftest "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/tests/conftest.py"
    click TestCore "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/tests/test_mypy_committed.py"
    click DocExamplesConfig "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/docs/examples/pre-commit-config.yaml"
    click DocExamplesCode "https://github.com/joosthart/pre-commit-hook-mypy/tree/main/docs/examples/"
    click README "https://github.com/joosthart/pre-commit-hook-mypy/blob/main/README.md"

    %% Styles
    classDef external fill:#d3d3d3,stroke:#888,stroke-width:1px
    classDef internal fill:#cce5ff,stroke:#338,stroke-width:1px
    classDef config fill:#d4edda,stroke:#3c763d,stroke-width:1px
    classDef docs fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:1px
```
