# jakobeha/type-sitter architecture

> Architecture diagram of the GitHub repository jakobeha/type-sitter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jakobeha/type-sitter
- Repository: https://github.com/jakobeha/type-sitter

## Overview

##### Main Components

a. Core Libraries (represent as rectangles):
- type-sitter-lib: Core runtime library
- type-sitter-gen: Code generation engine
- type-sitter-proc: Procedural macros interface
- yak-sitter: Optional tree-sitter wrapper
- type-sitter-cli: Command-line interface

b. External Dependencies (represent as hexagons):
- tree-sitter: The underlying parsing system
- Source Grammar Files (node-types.json)
- Query Files (*.scm)

- Grammar/Query files → type-sitter-gen → Generated Code
- Generated Code → type-sitter-lib (runtime usage)

- type-sitter-proc → type-sitter-gen
- type-sitter-cli → type-sitter-gen
- All components → type-sitter-lib

a. Code Generation Stage:
- Input Processing (node-types.json, query files)
- Type Generation
- Code Emission

b. Runtime Stage:
- Parser Integration
- Type-safe Node Handling
- Query Execution

##### Specific Implementation Details

a. type-sitter-gen:
- Node Type Generation
- Query Generation
- Custom Supertype Generation

b. type-sitter-lib:
- Typed Node Wrappers
- Query Execution
- Error Handling

a. Build-time Path:
- Build Script → type-sitter-gen → Generated Code

b. Macro Path:
- Procedural Macros → type-sitter-gen → Generated Code

c. CLI Path:
- CLI Tool → type-sitter-gen → Generated Code

**□ Core Library Component**
**⬡ External Dependency**
**◇ Generated Code**
**○ Processing Stage**

**→ Data Flow**
**⇢ Dependency**
**⇉ Usage Path**

**Blue: Core Components**
**Green: Input Sources**
**Orange: Generated Code**
**Purple: External Dependencies**
**Gray: Optional Components**

##### Additional Notes
- Version compatibility information (tree-sitter v0.24)
- Three different usage methods as separate paths
- Optional yak-sitter integration points
- Error handling flow
- File generation paths

Remember to include notes about the large code generation aspect (31K+ LOC for nodes, 6K+ for queries) as it's a significant characteristic of the system.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph External
        TS[tree-sitter v0.24]:::external
        GF["Grammar Files<br/>(node-types.json)"]:::external
        QF["Query Files<br/>(*.scm)"]:::external
    end

    subgraph "Core Libraries"
        TSL["type-sitter-lib<br/>(Runtime Library)"]:::core
        TSG["type-sitter-gen<br/>(Code Generator)"]:::core
        TSP["type-sitter-proc<br/>(Proc Macros)"]:::core
        TSC["type-sitter-cli<br/>(CLI Tool)"]:::core
        YS["yak-sitter<br/>(Optional Wrapper)"]:::optional
    end

    subgraph "Generation Components"
        NTG["Node Type<br/>Generator"]:::generator
        QG["Query<br/>Generator"]:::generator
        STG["Supertype<br/>Generator"]:::generator
    end

    subgraph "Runtime Components"
        NW["Node<br/>Wrappers"]:::runtime
        QE["Query<br/>Execution"]:::runtime
        EH["Error<br/>Handling"]:::runtime
    end

    subgraph "Generated Output"
        GC["Generated Code<br/>(37K+ LOC)"]:::output
    end

    %% Core Relationships
    GF --> TSG
    QF --> TSG
    TSG --> GC
    GC --> TSL
    TS --> TSL

    %% Generation Flow
    TSG --> NTG
    TSG --> QG
    TSG --> STG
    NTG --> GC
    QG --> GC
    STG --> GC

    %% Usage Paths
    TSP -.-> TSG
    TSC -.-> TSG
    YS -.-> TSL

    %% Runtime Components
    TSL --> NW
    TSL --> QE
    TSL --> EH

    %% Click Events
    click TSL "https://github.com/Jakobeha/type-sitter/blob/main/type-sitter-lib/src/lib.rs"
    click TSG "https://github.com/Jakobeha/type-sitter/blob/main/type-sitter-gen/src/lib.rs"
    click TSP "https://github.com/Jakobeha/type-sitter/blob/main/type-sitter-proc/src/lib.rs"
    click TSC "https://github.com/Jakobeha/type-sitter/blob/main/type-sitter-cli/src/main.rs"
    click YS "https://github.com/Jakobeha/type-sitter/blob/main/yak-sitter/src/lib.rs"
    click NTG "https://github.com/Jakobeha/type-sitter/tree/main/type-sitter-gen/src/node_types"
    click QG "https://github.com/Jakobeha/type-sitter/tree/main/type-sitter-gen/src/queries"
    click NW "https://github.com/Jakobeha/type-sitter/tree/main/type-sitter-lib/src/node"
    click QE "https://github.com/Jakobeha/type-sitter/tree/main/type-sitter-lib/src/query"
    click EH "https://github.com/Jakobeha/type-sitter/blob/main/type-sitter-lib/src/node/incorrect_kind.rs"

    %% Styling
    classDef core fill:#a8d1f0,stroke:#333
    classDef external fill:#d7aefb,stroke:#333
    classDef generator fill:#ffd700,stroke:#333
    classDef runtime fill:#90ee90,stroke:#333
    classDef output fill:#ffa07a,stroke:#333
    classDef optional fill:#d3d3d3,stroke:#333

    %% Legend
    subgraph Legend
        L1["Core Component"]:::core
        L2["External Dependency"]:::external
        L3["Generator Component"]:::generator
        L4["Runtime Component"]:::runtime
        L5["Generated Output"]:::output
        L6["Optional Component"]:::optional
    end
```
