# swiftlang/swift-syntax architecture

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

- Interactive diagram: https://gitdiagram.com/swiftlang/swift-syntax
- Repository: https://github.com/swiftlang/swift-syntax

## Overview

##### Main Components

a. Core Components:
- SwiftSyntax (main library)
- SwiftParser (parsing component)
- SwiftOperators (operator handling)
- SwiftDiagnostics (error reporting)
- SwiftSyntaxBuilder (syntax tree construction)
- SwiftSyntaxMacros (macro system)

b. Supporting Components:
- SwiftBasicFormat (formatting functionality)
- SwiftCompilerPlugin (compiler integration)
- SwiftIDEUtils (IDE integration utilities)
- Testing Infrastructure

**Top Layer (Client-Facing):**
**[SwiftSyntaxBuilder] <-> [SwiftSyntaxMacros]**
- ↓                     ↓
**Middle Layer (Processing):**
**[SwiftParser] <-> [SwiftSyntax Core] <-> [SwiftOperators]**
- ↓            ↓                      ↓
**Bottom Layer (Infrastructure):**
**[SwiftDiagnostics] <-> [SwiftBasicFormat] <-> [SwiftCompilerPlugin]**

##### Component Relationships

- Double lines: Bidirectional communication

##### Key Elements to Highlight

a. Parser Pipeline:
**Source Code -> SwiftParser -> Syntax Tree -> Macro Processing -> Final AST**

b. Macro Expansion Flow:
**SwiftSyntaxMacros -> SwiftCompilerPlugin -> Source Transformation**

##### Special Features

- Incremental parsing capability
- Macro expansion system
- Testing infrastructure connections
- IDE integration points

##### Additional Details

Annotations for:
- Version compatibility (Swift 5.9+)
- Build system integration (SwiftPM, Bazel)
- Testing components
- Documentation generation

##### Notes for Implementation

- Use standard UML notation where appropriate
- Clear boundaries between public and internal components
- Version compatibility markers

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef macro fill:#2ecc71,stroke:#27ae60,color:white
    classDef util fill:#f1c40f,stroke:#f39c12,color:black
    classDef diag fill:#e74c3c,stroke:#c0392b,color:white
    classDef ide fill:#9b59b6,stroke:#8e44ad,color:white
    classDef test fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Top Layer
    subgraph ClientLayer
        SyntaxBuilder["SwiftSyntaxBuilder"]:::macro
        SyntaxMacros["SwiftSyntaxMacros"]:::macro
        MacroExpansion["Macro Expansion System"]:::macro
    end

    %% Middle Layer
    subgraph ProcessingLayer
        Parser["SwiftParser"]:::core
        SyntaxCore["SwiftSyntax Core"]:::core
        Operators["SwiftOperators"]:::core
        LexicalLookup["Lexical Lookup"]:::core
    end

    %% Bottom Layer
    subgraph InfrastructureLayer
        Diagnostics["SwiftDiagnostics"]:::diag
        BasicFormat["SwiftBasicFormat"]:::util
        CompilerPlugin["SwiftCompilerPlugin"]:::util
        ParserDiag["Parser Diagnostics"]:::diag
    end

    %% Support Layer
    subgraph SupportLayer
        IDEUtils["SwiftIDEUtils"]:::ide
        CodeGen["Code Generation"]:::util
        Testing["Testing Infrastructure"]:::test
        IDEIntegration["IDE Integration"]:::ide
    end

    %% Relationships
    SyntaxBuilder <--> SyntaxMacros
    SyntaxMacros <--> MacroExpansion
    MacroExpansion --> CompilerPlugin
    
    Parser --> SyntaxCore
    SyntaxCore <--> Operators
    SyntaxCore --> LexicalLookup
    
    Parser --> ParserDiag
    ParserDiag --> Diagnostics
    
    SyntaxCore --> BasicFormat
    BasicFormat --> CompilerPlugin
    
    IDEUtils --> SyntaxCore
    IDEUtils --> IDEIntegration
    
    Testing -.-> SyntaxCore
    Testing -.-> Parser
    Testing -.-> Operators
    
    CodeGen --> SyntaxCore

    %% Click Events
    click SyntaxBuilder "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftSyntaxBuilder"
    click SyntaxMacros "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftSyntaxMacros"
    click MacroExpansion "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftSyntaxMacroExpansion"
    click Parser "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftParser"
    click SyntaxCore "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftSyntax"
    click Operators "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftOperators"
    click LexicalLookup "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftLexicalLookup"
    click Diagnostics "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftDiagnostics"
    click BasicFormat "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftBasicFormat"
    click CompilerPlugin "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftCompilerPlugin"
    click ParserDiag "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftParserDiagnostics"
    click IDEUtils "https://github.com/swiftlang/swift-syntax/tree/main/Sources/SwiftIDEUtils"
    click CodeGen "https://github.com/swiftlang/swift-syntax/tree/main/CodeGeneration/Sources/SyntaxSupport"
    click Testing "https://github.com/swiftlang/swift-syntax/tree/main/Tests/SwiftSyntaxTest"
    click IDEIntegration "https://github.com/swiftlang/swift-syntax/tree/main/EditorExtension/SwiftRefactorExtension"

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Macro Components"]:::macro
        L3["Utility Components"]:::util
        L4["Diagnostic Components"]:::diag
        L5["IDE Components"]:::ide
        L6["Testing Components"]:::test
    end
```
