# microsoft/vscode-pylint architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/vscode-pylint
- Repository: https://github.com/microsoft/vscode-pylint

## Overview

##### Project Type and Purpose
- This is a VS Code extension designed to offer integrated linting for Python using Pylint.
- It acts as a wrapper around Pylint (with a default bundled version of 3.3.4) and exposes configuration options such as custom linting arguments, working directory settings, and notification controls.
- The extension leverages both a client-side component (written in TypeScript) and a backend component (bundled as Python tool files implementing LSP support).

##### Analyzing the File Structure
- Top-Level Directories:
- The root contains configuration files (e.g., .eslintrc.json, .prettierrc.js, tsconfig.json, webpack.config.js) used to build and validate the TypeScript/JavaScript code.
- “src” contains the main extension source code. For example, src/extension.ts initializes and manages the extension, while src/common holds many utility modules (e.g., settings, logging, server orchestration).
- The “bundled/tool” directory contains Python scripts (such as lsp_server.py, lsp_runner.py, lsp_jsonrpc.py) that implement the backend LSP server which runs Pylint.
- “src/test” splits into both Python tests (for backend testing) and TS tests (for client-side functionality).
- Build and Deployment:
- The “build” directory includes scripts and pipeline definitions (e.g., azure-pipeline and update_ext_version scripts) for packaging and releasing the extension.
- The presence of .github workflows and actions indicates continuous integration set up for linting, testing, and code analysis.
- Other configuration files ensure consistency in development (e.g., devcontainer for VS Code remote development).

##### Key Components
- VS Code Extension Client:
- Extension’s entry point (src/extension.ts) and various supporting modules in src/common (e.g., constants.ts, logging.ts, settings.ts, server.ts).
- Integration with the VS Code API (commands, status bar notifications, log level settings).
- Bundled Python LSP Server:
- Backend bundled in “bundled/tool” which includes modules such as lsp_server.py (the main server), lsp_runner.py (managing the server process), lsp_jsonrpc.py (handling JSON-RPC requests), and other utility modules.
- That the LSP server is responsible for invoking Pylint (either the bundled version or one from the environment) and returning diagnostic information.
- Communication Layer:
- JSON-RPC protocol layer between the TypeScript client component and the Python LSP server component.
- Testing & Build Infrastructure:
- Test components (Python tests in src/test/python_tests, TS tests in src/test/ts_tests) to show how the system is validated.
- Briefly denote CI/CD pipelines (build folder and .github workflows) that ensure continuous integration and deployment.

##### Relationships and Interactions
- The client component (running within VS Code) listens for file change events, saves, and other interactions, which then trigger linting calls.
- Communication flows from the extension frontend to the backend LSP server:
- The extension starts (or restarts) the bundled Python LSP server.
- Through the JSON-RPC protocol, linting requests/data are transmitted and diagnostic results received.
- Configuration settings (from VS Code settings such as “pylint.args”, “pylint.cwd”, etc.) are used by the client to control how linting is executed.
- The build system process (webpack and build scripts) compiles and packages this overall solution for distribution on the Visual Studio Code Marketplace.

##### Architectural Patterns and Technologies
- The project follows a layered architecture involving:
- Client-side logic (extension code in TypeScript interacting with VS Code APIs).
- A backend service (Python-based LSP server) that abstracts Pylint integration.
- Design patterns include:
- Separation of concerns (different modules for settings, logging, and utilities).
- Use of the LSP pattern to separate editor-related events from linting processes.
- Technologies include Node.js/TypeScript, Python, JSON-RPC, and VS Code’s extension API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "VS Code Extension Client"
        extEntry("Extension Entry (extension.ts)"):::client
        common("Common Modules (src/common)"):::client
        clientJSON("Client JSON-RPC Handler (python.ts)"):::communication
    end

    subgraph "Communication Layer"
        jsonRpc("JSON-RPC Communication"):::communication
    end

    subgraph "Python LSP Server"
        lspServer("lsp_server.py"):::server
        lspRunner("lsp_runner.py"):::server
        lspJsonRpc("lsp_jsonrpc.py"):::server
        lspUtils("lsp_utils.py"):::server
        debugServer("_debug_server.py"):::server
    end

    subgraph "Testing & Build Infrastructure"
        testing("Testing Infrastructure (src/test)"):::testing
        subgraph "Build & Deployment"
            buildScripts("Build Scripts (build)"):::build
            ciCd("CI/CD Workflows (.github)"):::build
        end
    end

    %% Connections between components
    extEntry --> common
    common --> clientJSON
    clientJSON -->|"JSONRPC_request"| jsonRpc
    jsonRpc -->|"Invoke_LSP"| lspServer
    lspServer -->|"JSONRPC_response"| jsonRpc
    jsonRpc -->|"Response_to_client"| clientJSON

    %% Click Events
    click extEntry "https://github.com/microsoft/vscode-pylint/blob/main/src/extension.ts"
    click common "https://github.com/microsoft/vscode-pylint/tree/main/src/common/"
    click clientJSON "https://github.com/microsoft/vscode-pylint/blob/main/src/common/python.ts"
    click lspServer "https://github.com/microsoft/vscode-pylint/blob/main/bundled/tool/lsp_server.py"
    click lspRunner "https://github.com/microsoft/vscode-pylint/blob/main/bundled/tool/lsp_runner.py"
    click lspJsonRpc "https://github.com/microsoft/vscode-pylint/blob/main/bundled/tool/lsp_jsonrpc.py"
    click lspUtils "https://github.com/microsoft/vscode-pylint/blob/main/bundled/tool/lsp_utils.py"
    click debugServer "https://github.com/microsoft/vscode-pylint/blob/main/bundled/tool/_debug_server.py"
    click testing "https://github.com/microsoft/vscode-pylint/tree/main/src/test/"
    click buildScripts "https://github.com/microsoft/vscode-pylint/tree/main/build/"
    click ciCd "https://github.com/microsoft/vscode-pylint/tree/main/.github/"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef server fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef communication fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef testing fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef build fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
```
