# nicklockwood/swiftformat architecture

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

- Interactive diagram: https://gitdiagram.com/nicklockwood/swiftformat
- Repository: https://github.com/nicklockwood/swiftformat

## Overview

##### Main Components
- Core Formatting Engine:
– This is the heart of SwiftFormat and is implemented in the “Sources” directory (including subdirectories like Rules and Parsing). It contains the logic for tokenizing input Swift code, applying formatting rules, and generating formatted output.
- Command-Line Interface (CLI):
– Represented by the “CommandLineTool” module along with the SwiftFormat.xcodeproj and Package.swift; it wraps around the core engine to allow users to run SwiftFormat via the terminal.
- Editor Integration / Extensions:
– The “EditorExtension” folder contains separate parts for the Application (with its UI and storyboard) and the actual Extension code (with commands like FormatFileCommand, FormatSelectionCommand). This component shows how the formatter plugs into Xcode.
- Plugin & SPM Integration:
– The “Plugins” directory (e.g., SwiftFormatPlugin) and the “PluginTests” demonstrate how SwiftFormat is integrated into Swift Package Manager as a command plugin, as well as how other plugin-based integrations are supported.
- Snapshots and Examples:
– “Snapshots” contains various examples (Async, Expression, Layout, SwiftUI, etc.) and test cases which serve as reference use-cases and automated tests. They can be shown as a supporting component for demonstration and validation.
- Configuration & Rules:
– The configuration system (including the .swiftformat config files, Rules.md, and Options in the README) is crucial, so indicate how the configuration options flow into the core formatting engine.
- Testing and Continuous Integration:
– Directories such as “Tests,” “PerformanceTests,” and the GitHub workflows (.github/workflows) indicate that the project is tightly integrated with automated testing and CI (including GitHub Actions and Docker runs).

##### Relationships and Data Flow
- The CLI, Editor Extension, and Plugin components all serve as “clients” that invoke the core formatting engine.
- Data flows from user input (e.g., a Swift file in a text editor or on disk), into the CLI or extension which then passes the source code to the formatting engine.
- The engine applies formatting rules (configured using options from config files) and sends a formatted output back to the invoker.
- Test suites and snapshot examples validate that the core engine’s outputs are correct.
- External integrations (Git pre-commit hooks, CI workflows, Docker) call the CLI to run the formatting process in various environments.

##### Architectural Patterns and Design Principles
- Modularity: Each integration point is an independent “adapter” using the core library.
- Separation of Concerns: The core formatting functionalities (handled in Sources/Rules and Parsing) are decoupled from presentation layers (i.e., CLI vs. Xcode extension).
- Extensibility: The design allows third-party plugin integrations, configurable rules, and even version-specific behaviors (e.g., Swift language mode settings).

##### Relevant Technologies, Frameworks, and Libraries
- Swift (various versions): The project is built using Swift and supports multiple language modes.
- Swift Package Manager: Used both for building the core tool and for integrating the SPM plugin.
- Xcode: Powers the source editor extension, and the project includes an Xcode project (SwiftFormat.xcodeproj) to build components for macOS.
- GitHub Actions and Docker: Used for CI and automated testing/deployment.
- CocoaPods and additional scripts that facilitate integration with various editors (VSCode, Sublime Text, Nova).

##### Instructing the Principal Software Engineer
– Client-side invocations (CLI, Extension, Plugin) → Core Formatting Engine → Output back to storage or IDE.
– Configuration flows into the engine.
– Test suites and CI integrations that continuously validate the behavior.
- Be detailed and explicit in separating the architecture into discrete components that illustrate how each integration point impacts the overall formatting process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Integration Adapters
    subgraph "Integration Adapters"
        CLI_Main["Command-Line Interface (CLI: CommandLineTool/main.swift)"]:::integration
        CLI_Package["Package Manager (Package.swift)"]:::integration
        Editor_App["Editor App (EditorExtension/Application)"]:::integration
        Editor_Ext["Editor Extension (EditorExtension/Extension)"]:::integration
        Plugin_Node["SPM Plugin (Plugins/SwiftFormatPlugin)"]:::integration
        Plugin_Tests["Plugin Tests (PluginTests)"]:::integration
    end

    %% Core Formatting Engine
    subgraph "Core Formatting Engine"
        Core_Engine["Core Formatting Engine (Sources)"]:::core
        Core_Rules["Formatting Rules (Sources/Rules)"]:::core
    end

    %% Configuration & Rules
    subgraph "Configuration & Rules"
        Config_Files["Configuration Files (.swiftformat)"]:::config
        Rules_Doc["Formatting Documentation (Rules.md)"]:::config
    end

    %% Support & Validation
    subgraph "Support & Validation"
        Snapshots_Node["Snapshots & Examples (Snapshots)"]:::testing
        Tests_Node["Tests (Tests)"]:::testing
        Performance_Node["Performance Tests (PerformanceTests)"]:::testing
        CI_Node["GitHub Workflows (CI)"]:::testing
    end

    %% Data Flow from Integration to Core
    CLI_Main -->|"callsFormattingAPI"| Core_Engine
    CLI_Package -->|"callsFormattingAPI"| Core_Engine
    Editor_App -->|"callsFormattingAPI"| Core_Engine
    Editor_Ext -->|"callsFormattingAPI"| Core_Engine
    Plugin_Node -->|"callsFormattingAPI"| Core_Engine
    Plugin_Tests -->|"callsFormattingAPI"| Core_Engine

    %% Core Engine internal relationship
    Core_Engine -->|"usesRules"| Core_Rules

    %% Configuration input into Core Engine
    Config_Files -->|"configurationInput"| Core_Engine
    Rules_Doc -->|"configurationInput"| Core_Engine

    %% Validation and Testing feed into Core Engine
    Snapshots_Node -->|"validateOutput"| Core_Engine
    Tests_Node -->|"validateOutput"| Core_Engine
    Performance_Node -->|"validateOutput"| Core_Engine

    %% Automated CI invoking CLI
    CI_Node -->|"automatedInvocation"| CLI_Main

    %% Click Events
    click Core_Engine "https://github.com/nicklockwood/swiftformat/tree/main/Sources"
    click Core_Rules "https://github.com/nicklockwood/swiftformat/tree/main/Sources/Rules"
    click CLI_Main "https://github.com/nicklockwood/swiftformat/blob/main/CommandLineTool/main.swift"
    click CLI_Package "https://github.com/nicklockwood/swiftformat/blob/main/Package.swift"
    click Editor_App "https://github.com/nicklockwood/swiftformat/tree/main/EditorExtension/Application"
    click Editor_Ext "https://github.com/nicklockwood/swiftformat/tree/main/EditorExtension/Extension"
    click Plugin_Node "https://github.com/nicklockwood/swiftformat/tree/main/Plugins/SwiftFormatPlugin"
    click Plugin_Tests "https://github.com/nicklockwood/swiftformat/tree/main/PluginTests"
    click Config_Files "https://github.com/nicklockwood/swiftformat/blob/main/.swiftformat"
    click Rules_Doc "https://github.com/nicklockwood/swiftformat/blob/main/Rules.md"
    click Snapshots_Node "https://github.com/nicklockwood/swiftformat/tree/main/Snapshots"
    click Tests_Node "https://github.com/nicklockwood/swiftformat/tree/main/Tests"
    click Performance_Node "https://github.com/nicklockwood/swiftformat/tree/main/PerformanceTests"
    click CI_Node "https://github.com/nicklockwood/swiftformat/tree/main/.github/workflows"

    %% Styles
    classDef core fill:#FFC107,stroke:#333,stroke-width:2px;
    classDef integration fill:#03A9F4,stroke:#333,stroke-width:2px;
    classDef config fill:#8BC34A,stroke:#333,stroke-width:2px;
    classDef testing fill:#E91E63,stroke:#333,stroke-width:2px;
```
