# smx-smx/valasharp architecture

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

- Interactive diagram: https://gitdiagram.com/smx-smx/valasharp
- Repository: https://github.com/smx-smx/valasharp

## Overview

##### Project Type & Purpose
- ValaSharp is a compiler toolchain for the Vala language, fully re-written in C#/.NET.
- It consists of a core compiler library, a CLI front-end (ValaCompiler), auxiliary tools (VapiGen, ValaConfig), an experimental Language Server (for VS Code), and a large test harness.

##### Top-Level Components (from file tree)
a. Core Libraries (blue)
– Lang: lexer, parser, AST, semantic analysis, symbol table, flow analyzer.
– CLanguage: C-AST model & writer (represents the generated C code).
– CCodeGen: modules that walk the C-AST and emit C source (a plugin/pipeline architecture for code generation).
– GLibPorts: .NET bindings to GLib and related low-level native interop.
– Utils: misc. helpers (memory mapping, fast views, extensions).
b. Compiler Host (green)
– ValaCompilerLib: exposes CompilerOptions + compile pipeline (invokes Lang → semantic → CCodeGen → writes C files).
– ValaCompiler: console app; parses args (App.config), invokes ValaCompilerLib, then shells out to a C compiler (e.g., gcc/clang).
– ValaConfig: configuration reader (searches compile options, pkg-config integration).
– VapiGen: tool that generates VAPI metadata by leveraging CompilerLib.
c. Language Server (orange)
– ValaLanguageServer: LSP server implementation (handles text-document/didChange, validation, code search, AST traversal).
– client/extension.ts: VS Code extension that communicates with the server over the Language Server Protocol.
d. Test Harness (yellow)
– ValaTests: test spec files (.vala, .test), ValaTestRunner (C# runner), regression scripts (PHP, shell).

- Lay out components in logical layers from left to right or top to bottom:
1. Input & Configuration
- Vala source files + CLI args (ValaCompiler)
- ValaConfig (reads .vala files, include paths, pkg-config data)
2. Frontend (Lang)
- Scanner → Parser → AST (Lang/Parser, Lang/CodeNodes)
- Semantic Analyzer & FlowAnalyzer → SymbolResolver → type checking
3. Backend
- CodeGenerator (Lang/CodeGenerator) → emits intermediate C-AST (CLanguage)
- CCodeGen Modules → emit .c/.h source files
- GLibPorts library (runtime) linked in generated code
- External C Compiler (gcc/clang) → final native binary
4. Host Tools
- ValaCompilerLib (pipeline orchestrator)
- ValaCompiler CLI (shell front-end)
- VapiGen & other tooling
5. Language Server
- LSP Server (ValaLanguageServer) uses CompilerLib pipeline for parse/analysis
- VS Code Extension (client) ↔ Server (via JSON-RPC over stdio or socket)
6. Tests
- ValaTestRunner & test scripts invoke ValaCompilerLib for each test case

##### Relationships & Data Flows
- CLI → CompilerLib → Lang(frontend) → Semantic → CodeGen → writes C code → native compiler
- CompilerLib → VapiGen (reads AST, emits VAPI)
- Language Server ↔ CompilerLib for on-the-fly parsing and validation
- VS Code client → LSP server (bidirectional JSON-RPC)
- Tests → ValaTestRunner → CompilerLib → compare expected output

##### Key Architectural Patterns
- Layered pipeline (lexer → parser → AST → semantic → codegen)
- Plugin-style codegen modules in CCodeGen (each module handles one feature)
- Shared core library (ValaCompilerLib) reused by CLI, VapiGen, Language Server, Tests
- Clear separation between front-end (Lang) and back-end (CLanguage + CCodeGen)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Configuration
    subgraph "Input & Configuration"
        direction TB
        ValaSrc["/Vala Source Files/"]:::io
        ValaArgs["CLI Args"]:::io
        ValaConfigNode["Configuration Reader\n(ValaConfig/Config.cs)"]:::tool
    end

    %% Frontend
    subgraph "Frontend (Lang)" 
        direction TB
        Scanner["Scanner\n(Lang/Lexer)"]:::core
        Parser["Parser\n(Lang/Parser/Parser.cs)"]:::core
        AST["AST Builder\n(Lang/CodeNodes)"]:::core
        Semantic["Semantic & Flow Analyzer\n(Lang/SemanticAnalyzer.cs\nLang/FlowAnalyzer.cs)"]:::core
    end

    %% Backend
    subgraph "Backend"
        direction TB
        CGen["Code Generator\n(Lang/Code/CodeGenerator.cs)"]:::core
        IntermediateAST["C-AST Model\n(CLanguage/)"]:::core
        CCodeGenModules["CCodeGen Modules\n(CCodeGen/Modules/)"]:::core
        GLibRuntime["GLib Runtime Bindings\n(GLibPorts/)"]:::core
        COutput["/C Source Files/"]:::io
        NativeCompiler["External C Compiler\n(gcc/clang)"]:::external
    end

    %% Host Tools
    subgraph "Host Tools"
        direction TB
        CompilerLib["Pipeline Orchestrator\n(ValaCompilerLib/Compiler.cs)"]:::tool
        ValaCompilerCLI["CLI Front-end\n(ValaCompiler/Program.cs)"]:::tool
        VapiGenNode["VAPI Generator\n(VapiGen/Program.cs)"]:::tool
    end

    %% Language Server
    subgraph "Language Server"
        direction TB
        LanguageServerNode["[[LSP Server\n(ValaLanguageServer/)]]"]:::lsp
        VSCodeClient["VS Code Extension\n(client/src/extension.ts)"]:::lsp
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        ValaTests["Test Runner & Specs\n(ValaTests/)"]:::test
    end

    %% Connections
    ValaSrc -->|provides| Parser
    ValaArgs -->|passed to| CompilerLib
    ValaConfigNode -->|configures| CompilerLib

    CompilerLib -->|invokes| Scanner
    Scanner --> Parser
    Parser --> AST
    AST --> Semantic
    Semantic --> CGen
    CGen --> IntermediateAST
    IntermediateAST --> CCodeGenModules
    CCodeGenModules --> COutput
    CCodeGenModules --> GLibRuntime
    COutput --> NativeCompiler

    CompilerLib -->|used by| VapiGenNode
    CompilerLib -->|used by| LanguageServerNode
    VSCodeClient -->|JSON-RPC| LanguageServerNode

    ValaTests -->|runs| CompilerLib
    ValaTests -->|validates via| ValaTests

    ValaCompilerCLI -->|calls| CompilerLib

    %% Click Events
    click Parser "https://github.com/smx-smx/valasharp/blob/master/Lang/Parser/Parser.cs"
    click Semantic "https://github.com/smx-smx/valasharp/blob/master/Lang/SemanticAnalyzer.cs"
    click AST "https://github.com/smx-smx/valasharp/tree/master/Lang/CodeNodes"
    click CGen "https://github.com/smx-smx/valasharp/blob/master/Lang/Code/CodeGenerator.cs"
    click IntermediateAST "https://github.com/smx-smx/valasharp/tree/master/CLanguage/"
    click CCodeGenModules "https://github.com/smx-smx/valasharp/tree/master/CCodeGen/Modules/"
    click GLibRuntime "https://github.com/smx-smx/valasharp/tree/master/GLibPorts/"
    click CompilerLib "https://github.com/smx-smx/valasharp/blob/master/ValaCompilerLib/Compiler.cs"
    click ValaCompilerCLI "https://github.com/smx-smx/valasharp/blob/master/ValaCompiler/Program.cs"
    click ValaConfigNode "https://github.com/smx-smx/valasharp/blob/master/ValaConfig/Config.cs"
    click VapiGenNode "https://github.com/smx-smx/valasharp/blob/master/VapiGen/Program.cs"
    click LanguageServerNode "https://github.com/smx-smx/valasharp/tree/master/ValaLanguageServer/"
    click VSCodeClient "https://github.com/smx-smx/valasharp/blob/master/ValaLanguageServer/client/src/extension.ts"
    click ValaTests "https://github.com/smx-smx/valasharp/tree/master/ValaTests/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef tool fill:#E6F5D0,stroke:#2F842F,color:#2F842F
    classDef lsp fill:#FFE8B0,stroke:#D28E00,color:#D28E00
    classDef test fill:#FFF3C4,stroke:#AB6C00,color:#AB6C00
    classDef io fill:#F0F0F0,stroke:#888,stroke-dasharray: 2 2
    classDef external fill:#FFEDED,stroke:#D93025,color:#D93025
```
