# kaby76/antlrvsix architecture

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

- Interactive diagram: https://gitdiagram.com/kaby76/antlrvsix
- Repository: https://github.com/kaby76/antlrvsix

## Overview

##### Project type and purpose
- AntlrVSIX is an open‑source language tooling suite built around the Language Server Protocol.
- It delivers grammar‐editing features (tagging, go‑to‑def, hover, find‑refs, rename, formatting), grammar analysis, refactoring, conversion via:
- A .NET LSP server (C#)
- Multiple thin “client” adapters: VS IDE extension, VS Code extension (TypeScript), Emacs Lisp plugin, and a CLI (“Trash”).

##### File structure
- Top‑level “shared” libraries:
- Logger/ (Log.cs)
- LspHelpers/ (LSP protocol types, helper streams)
- Options/ (per‑client configuration system)
- Core server:
- Server/ (LSPServer.cs, Program.cs, language‐targeting code)
- Clients:
- VsIde/ (C# VSIX extension project, Visual Studio LSP client shim, menus, commands)
- VsCode/ (TS extension.ts, package.json, server launch shim)
- Emacs/ (lsp‑antlr.el, Emacs client readme)
- Command‑line shell:
- Trash under <root>/Trash (invokes parse/transform APIs out of process)
- Transforms:
- transforms/ (scripts implementing individual grammar refactorings)
- Tests:
- test/ (sample grammars, JUnit tests, Java project for integration)

##### Key README insights
- All clients communicate with the same LSP server process.
- Server internals use Antlr4, Antlr4BuildTasks, XPath2, S‑expressions for parse trees.
- Trash is a CLI shell that serializes parse tree state as JSON, enabling out‑of‑process commands.
- VS IDE uses Microsoft.VisualStudio.LanguageServer.Client; VS Code spawns the server via Node.

a. Main components
- Shared libraries: Logger, LspHelpers, Options
- Core LSP Server (.NET)
- Clients:
- VS IDE extension (C# VSIX)
- VS Code extension (TypeScript + Node)
- Emacs plugin (Elisp)
- Trash CLI (Console app)
- Transform modules (tree refactorings)
- External dependencies: Antlr4 runtime, .NET SDK, Node.js, Visual Studio, VS Code, Emacs

b. Relationships & data flow
- Clients ↔ LSP Server:
- VS IDE uses in‑process NuGet LSP client → named pipes or in‑proc host
- VS Code uses stdio or IPC via Node child_process.spawn
- Emacs uses lsp-mode over stdio
- Trash invokes server APIs directly or via command line serialization
- LSP Server → Core parsing engine → Antlr4 grammar parser → parse tree → XPath/transform modules → analysis/refactor results → back to server → JSON‑RPC responses → clients

c. Architectural patterns & design principles
- Modular “shared‑library” pattern separating cross‑cutting concerns (logging, protocol types, options)
- Language Server Protocol façade isolating client‑specific shims
- Plugin/extension model per‑editor
- Out‑of‑process CLI model with JSON serialization for extensibility

d. Technologies/frameworks
- C#, .NET Core (Server, VS IDE, Logger, LspHelpers, Options, Trash)
- Antlr4 & Antlr4BuildTasks for grammar parsing
- XPath2, S‑expression libraries for tree queries
- Microsoft.VisualStudio.LanguageServer.Client (VS IDE)
- TypeScript, Node.js (VS Code)
- Emacs Lisp (Emacs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Shared Libraries
    subgraph "Shared Libraries"
        Logger["Logger"]:::shared
        LspHelpers["LspHelpers"]:::shared
        OptionsLib["Options"]:::shared
    end

    %% Core Server
    subgraph "Core LSP Server"
        ServerCore["LSP Server"]:::core
        JSONDispatcher["JSON‑RPC\nDispatcher"]:::coreInternal
        ReqHandlers["Request\nHandlers"]:::coreInternal
        AntlrParser["Antlr4\nParser Module"]:::coreInternal
        TransformEngine["Transform\nEngine"]:::coreInternal
    end

    %% Clients
    subgraph "Clients"
        VSIDE["VS IDE Extension"]:::vside
        VSCode["VS Code Extension"]:::vscode
        Emacs["Emacs Plugin"]:::emacs
        Trash["Trash CLI"]:::cli
    end

    %% Transforms
    subgraph "Transform Modules"
        RemoveParen["remove-useless-parentheses"]:::transform
        ReplaceLiterals["replace-literals"]:::transform
    end

    %% Testing
    subgraph "Tests & Samples"
        TestSamples["Sample Grammars & Tests"]:::test
    end

    %% External Dependencies
    subgraph "External Dependencies"
        AntlrRuntime["Antlr4\nRuntime"]:::external
        DotNetSDK[".NET Core SDK"]:::external
        NodeJS["Node.js"]:::external
        VSHost["Visual Studio Host"]:::external
        VSCodeHost["VS Code Host"]:::external
        EmacsHost["Emacs Host"]:::external
    end

    %% Shared libraries into server and clients
    Logger --> ServerCore
    LspHelpers --> ServerCore
    OptionsLib --> ServerCore
    Logger --> VSIDE
    LspHelpers --> VSIDE
    OptionsLib --> VSIDE
    Logger --> VSCode
    LspHelpers --> VSCode
    OptionsLib --> VSCode
    Logger --> Emacs
    LspHelpers --> Emacs
    OptionsLib --> Emacs
    Logger --> Trash
    LspHelpers --> Trash
    OptionsLib --> Trash

    %% Clients → ServerCore
    VSIDE -->|"in‑proc API / Named Pipe"| ServerCore
    VSCode -->|"JSON‑RPC over stdio / IPC"| ServerCore
    Emacs -->|"JSON‑RPC over stdio"| ServerCore
    Trash -->|"CLI API / JSON Serialization"| ServerCore

    %% Server internals flow
    ServerCore --> JSONDispatcher
    JSONDispatcher --> ReqHandlers
    ReqHandlers --> AntlrParser
    AntlrParser --> TransformEngine
    TransformEngine --> ReqHandlers

    %% Transforms hooking
    TransformEngine --> RemoveParen
    TransformEngine --> ReplaceLiterals
    RemoveParen --> TransformEngine
    ReplaceLiterals --> TransformEngine

    %% Testing
    TestSamples --> ServerCore
    TestSamples --> TransformEngine

    %% External dependencies into server and clients
    AntlrRuntime --> ServerCore
    DotNetSDK --> ServerCore
    NodeJS --> VSCode
    VSHost --> VSIDE
    VSCodeHost --> VSCode
    EmacsHost --> Emacs

    %% Click Events - Shared Libraries
    click Logger "https://github.com/kaby76/antlrvsix/blob/master/Logger/Log.cs"
    click Logger "https://github.com/kaby76/antlrvsix/blob/master/Logger/Logger.csproj"
    click LspHelpers "https://github.com/kaby76/antlrvsix/blob/master/LspHelpers/LspHelpers.csproj"
    click LspHelpers "https://github.com/kaby76/antlrvsix/blob/master/LspHelpers/EchoStream.cs"
    click LspHelpers "https://github.com/kaby76/antlrvsix/blob/master/LspHelpers/AssertFailedException.cs"
    click LspHelpers "https://github.com/kaby76/antlrvsix/blob/master/LspHelpers/ValueCheck.cs"
    click OptionsLib "https://github.com/kaby76/antlrvsix/blob/master/Options/Options.csproj"
    click OptionsLib "https://github.com/kaby76/antlrvsix/blob/master/Options/Option.cs"

    %% Click Events - Core Server
    click ServerCore "https://github.com/kaby76/antlrvsix/blob/master/Server/LSPServer.cs"
    click ServerCore "https://github.com/kaby76/antlrvsix/blob/master/Server/Server.csproj"
    click ServerCore "https://github.com/kaby76/antlrvsix/blob/master/Server/Program.cs"
    click ServerCore "https://github.com/kaby76/antlrvsix/blob/master/Server/LanguageServerTarget.cs"
    click ServerCore "https://github.com/kaby76/antlrvsix/blob/master/Server/Dup.cs"

    %% Click Events - VS IDE Extension
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/AntlrVSIX.csproj"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/AntlrLanguageClient.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/AntlrContentDefinition.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/GetVSVersion.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/Constants.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/source.extension.vsixmanifest"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/Helpers.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/IVsTextViewExtensions.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/ViewCreationListener.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/Properties/AssemblyInfo.cs"
    click VSIDE "https://github.com/kaby76/antlrvsix/blob/master/VsIde/VSPackage.resx"

    %% Click Events - VS Code Extension
    click VSCode "https://github.com/kaby76/antlrvsix/blob/master/VsCode/package.json"
    click VSCode "https://github.com/kaby76/antlrvsix/blob/master/VsCode/tsconfig.json"
    click VSCode "https://github.com/kaby76/antlrvsix/blob/master/VsCode/src/extension.ts"
    click VSCode "https://github.com/kaby76/antlrvsix/blob/master/VsCode/server/note.md"
    click VSCode "https://github.com/kaby76/antlrvsix/blob/master/VsCode/clean.sh"
    click VSCode "https://github.com/kaby76/antlrvsix/blob/master/VsCode/install.sh"
    click VSCode "https://github.com/kaby76/antlrvsix/blob/master/VsCode/install-cmd.bat"

    %% Click Events - Emacs Plugin
    click Emacs "https://github.com/kaby76/antlrvsix/blob/master/Emacs/lsp-antlr.el"
    click Emacs "https://github.com/kaby76/antlrvsix/blob/master/Emacs/readme.md"

    %% Click Events - Transforms
    click RemoveParen "https://github.com/kaby76/antlrvsix/tree/master/transforms/remove-useless-parentheses/"
    click ReplaceLiterals "https://github.com/kaby76/antlrvsix/tree/master/transforms/replace-literals/"

    %% Click Events - Tests & Samples
    click TestSamples "https://github.com/kaby76/antlrvsix/blob/master/test/A.g4"
    click TestSamples "https://github.com/kaby76/antlrvsix/blob/master/test/A2.g4"
    click TestSamples "https://github.com/kaby76/antlrvsix/blob/master/test/A3.g4"
    click TestSamples "https://github.com/kaby76/antlrvsix/blob/master/test/Animal.java"
    click TestSamples "https://github.com/kaby76/antlrvsix/blob/master/test/Dog.java"
    click TestSamples "https://github.com/kaby76/antlrvsix/blob/master/test/FormatterTest.java"
    click TestSamples "https://github.com/kaby76/antlrvsix/tree/master/test/jdt.ls‑java-project/"

    %% Click Events - Trash CLI
    click Trash "https://github.com/kaby76/antlrvsix/blob/master/doc-8.2/Trash.md"

    %% Styles
    classDef shared fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef core fill:#a8d1ff,stroke:#333,stroke-width:1px
    classDef coreInternal fill:#cfe8ff,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef vside fill:#b2f2b2,stroke:#333,stroke-width:1px
    classDef vscode fill:#fff3b2,stroke:#333,stroke-width:1px
    classDef emacs fill:#ffddb2,stroke:#333,stroke-width:1px
    classDef cli fill:#ffb2b2,stroke:#333,stroke-width:1px
    classDef transform fill:#d1b2ff,stroke:#333,stroke-width:1px
    classDef test fill:#e6e6e6,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef external fill:#ffffff,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
