# h1ghbre4k3r/pesca-lang architecture

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

- Interactive diagram: https://gitdiagram.com/h1ghbre4k3r/pesca-lang
- Repository: https://github.com/h1ghbre4k3r/pesca-lang

## Overview

##### Project type and purpose
- This is a compiler-style project written in Rust, implementing an experimental programming language called “Pesca”.
- It provides:
- A core library (`why_lib`) that performs lexing, parsing, and type checking
- A derive macro crate (`lex_derive`) to generate lexers at compile time
- Two CLI front-ends:
– `yc` (the compiler driver)
– `yls` (the language-server for editor integration)
- Documentation (in `docs/`) and example programs under `examples/`.

##### File structure
- Top-level Cargo workspace with `Cargo.toml` and two binaries in `src/bin/`: `yc.rs` and `yls.rs`.
- `crates/lex_derive`: a Rust proc-macro crate that generates lexing code based on token definitions.
- `crates/why_lib`: the core library, subdivided into modules:
- `lexer/` – definitions for tokens, lexmap, and the generated lexer
- `parser/` – parser combinators, `ParseState`, and AST definitions (`ast/`)
- `typechecker/` – context, error handling, scope management, and the construction of a typed AST
- `docs/`: mdBook sources describing language features and usage.
- `examples/`: sample `.why` programs used to test the language front end.

##### Readme insights
- Emphasizes that “everything is an expression” and outlines language syntax (expressions, control flow, functions).
- Mentions that the executable is rudimentary but that the project is a playground for restarting a programming language.

##### Main components and relationships
a. Components
- Source code files (`.why`)
- Compiler binary (`yc`)
- Language server binary (`yls`)
- Core library (`why_lib`):
– Lexer (proc-macro generated via `lex_derive`)
– Parser (parser combinators → AST)
– Typechecker (untyped AST → typed AST)
- Derive macro crate (`lex_derive`)
- Documentation (mdBook)
- Examples
b. Interactions / Data flow
1. `yc` / `yls` loads a `.why` source file
2. `why_lib::lexer` (with code generated by `lex_derive`) tokenizes input → stream of tokens
3. `why_lib::parser` consumes tokens → constructs an untyped AST
4. `why_lib::typechecker` consumes untyped AST → produces a typed AST or errors
5. Depending on CLI:
– `yc` might proceed to code generation or IR (not yet implemented)
– `yls` uses AST and typed AST to provide editor services
c. Architectural patterns / design principles
- Pipeline architecture (lexer → parser → typechecker → [future] codegen)
- Separation of concerns: proc-macro crate (`lex_derive`) separated from core logic
- Library + CLI front-ends pattern – reusing `why_lib` for multiple executables
d. Key technologies and frameworks
- Rust Cargo workspace and crates
- Rust proc-macros (`lex_derive`)
- Parser combinators in Rust
- mdBook for documentation

##### Elements
- Source files (.why)
- `yc` binary
- `yls` binary
- `lex_derive` proc-macro crate
- Documentation and examples as side artifacts
- Another for binaries

##### Detail
- That both `yc` and `yls` share the same pipeline
- A “future” codegen stage to capture the full intended architecture

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Input
    Source["Source Files (.why)"]:::artifact

    %% CLI Binaries Layer
    subgraph "CLI Front-Ends"
        direction TB
        YC["yc (Compiler Driver)"]:::binary
        YLS["yls (Language Server)"]:::binary
    end

    %% Core Library Layer
    subgraph "Core Library (why_lib)" 
        direction TB
        WL["why_lib"]:::library
        subgraph "Lexer Module" 
            direction TB
            LEX["Lexer\n(proc-macro generated)"]:::library
            LM["LexMap"]:::library
            TOK["Token Definitions"]:::library
        end
        subgraph "Parser Module"
            direction TB
            PAR["Parser\n(combinators)"]:::library
            PS["ParseState"]:::library
            AST["AST Definitions"]:::library
        end
        subgraph "Typechecker Module"
            direction TB
            TC["Typechecker"]:::library
            CONT["Context & Errors & Scope"]:::library
            TAST["Typed AST"]:::library
            TYPES["Types"]:::library
        end
    end

    %% Compile-Time Proc-Macro Crate
    subgraph "Proc-Macro Crate (compile-time)" 
        direction TB
        LD["lex_derive"]:::compile
        LDTOK["lex_derive::token"]:::compile
        LDEQ["lex_derive::loose_eq"]:::compile
    end

    %% Future Codegen Placeholder
    Future["Future Codegen / IR"]:::future

    %% Documentation & Examples
    subgraph "Artifacts"
        direction TB
        Docs["Documentation (mdBook)"]:::artifact
        Exs["Example Programs"]:::artifact
    end

    %% Data Flows
    Source --> YC
    Source --> YLS
    YC --> WL
    YLS --> WL

    LD --> LEX
    WL --> PAR
    WL --> TC

    LEX --> PAR
    PAR --> TC
    TC --> Future

    %% Artifact Links
    Docs -.-> Source
    Exs -.-> Source

    %% Click Events
    click WL "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/lib.rs"
    click LEX "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/lexer/mod.rs"
    click LM "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/lexer/lexmap.rs"
    click TOK "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/lexer/token.rs"
    click PAR "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/parser/mod.rs"
    click PS "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/parser/parse_state.rs"
    click AST "https://github.com/h1ghbre4k3r/pesca-lang/tree/main/crates/why_lib/src/parser/ast/"
    click CONT "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/typechecker/context.rs"
    click TC "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/typechecker/mod.rs"
    click TAST "https://github.com/h1ghbre4k3r/pesca-lang/tree/main/crates/why_lib/src/typechecker/typed_ast/"
    click TYPES "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/why_lib/src/typechecker/types.rs"
    click LD "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/lex_derive/src/lib.rs"
    click LDTOK "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/lex_derive/src/token.rs"
    click LDEQ "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/crates/lex_derive/src/loose_eq.rs"
    click YC "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/src/bin/yc.rs"
    click YLS "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/src/bin/yls.rs"
    click Docs "https://github.com/h1ghbre4k3r/pesca-lang/blob/main/docs/book.toml"
    click Exs "https://github.com/h1ghbre4k3r/pesca-lang/tree/main/examples/"

    %% Styles
    classDef compile fill:#FFD700,stroke:#B8860B,color:#000
    classDef library fill:#87CEEB,stroke:#4682B4,color:#000
    classDef binary fill:#98FB98,stroke:#2E8B57,color:#000
    classDef artifact fill:#D3D3D3,stroke:#A9A9A9,color:#000
    classDef future fill:#FFB6C1,stroke:#CD5C5C,color:#000
```
