# lucassus/lucky-script architecture

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

- Interactive diagram: https://gitdiagram.com/lucassus/lucky-script
- Repository: https://github.com/lucassus/lucky-script

## Overview

##### Project Type & Purpose
- The project is a full-fledged interpreter for a custom programming language.
- It supports arithmetic operations, user-defined functions (including higher-order functions), control flow (if statements), recursion, lexical scoping, and dynamic scoping.
- It also includes a sandbox directory (lark-sandbox) which seems to experiment with grammar definitions (e.g., JSON, lucky_script) using Lark (a parsing framework), likely to validate or compare grammar definitions.

##### Identifying Main Components
- REPL: The entry point (src/repl.ts) that accepts user input and drives the process.
- Lexer: Responsible for tokenizing the input. Located under src/Lexer with clear submodules for recognizers (e.g., Comment, Identifier, Numeral) and associated tests.
- Parser: Located under src/Parser, it takes tokens from the Lexer and builds an Abstract Syntax Tree (AST). It includes utility files like Lookahead.
- Interpreter: Found in src/Interpreter, it executes the AST, uses a Symbol Table for managing scope, and processes language constructs like functions and closures.
- Object System: The Interpreter has subcomponents for various runtime objects, such as LuckyNumber, LuckyBoolean, LuckyFunction, and LuckyObject.
- Error Handling: Each component includes its own error modules (e.g., src/Interpreter/errors.ts, src/Parser/errors.ts, src/Lexer/errors.ts) to manage syntax, lexical, and runtime issues.
- Testing & CI: There are test files across the modules (using Jest) plus GitHub workflows (.github/workflows) for CI, ensuring quality.

##### Relationships & Flow
- Data Flow: Start with the REPL accepting source code → passes to Lexer for tokenization → Lexer outputs tokens to the Parser → Parser generates an AST → AST is fed to the Interpreter for execution.
- Error Propagation: At each stage (Lexer, Parser, Interpreter), if errors occur, they are caught by the respective error mechanisms and communicated (possibly with custom error messages) back to the REPL.
- Scope and Closure Handling: Highlight that the Symbol Table managed by the Interpreter supports dynamic scopes and closure properties, meaning variable bindings can change based on runtime environment.

##### Architectural Patterns & Technologies
- Layered Pipeline: A clear pipeline where each phase (Lexing, Parsing, Interpreting) is a distinct layer.
- Modularity: The separation into distinct directories (Lexer, Parser, Interpreter) showcases a modular approach.
- Test-Driven Structure: Numerous test files in each module indicate a strong focus on unit testing.
- Use of TypeScript and Node.js with yarn and ts-node to facilitate rapid development and easy execution of the REPL.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Main Input Component
    REPL["REPL (src/repl.ts)"]:::input

    %% Lexing Stage
    subgraph "Lexing Stage"
        LEX["Lexer Module"]:::analysis
        REC["Recognizers (Comment, Identifier, Numeral)"]:::analysis
        LEX_ERR["Lexer Errors"]:::errors
    end

    %% Parsing Stage
    subgraph "Parsing Stage"
        PAR["Parser Module"]:::analysis
        LOOK["Lookahead & AST Node"]:::analysis
        PAR_ERR["Parser Errors"]:::errors
    end

    %% Interpreting Stage
    subgraph "Interpreting Stage"
        INT["Interpreter Module"]:::execution
        SYM["Symbol Table"]:::execution
        RUNTIME["Runtime Objects (LuckyBoolean, LuckyFunction, LuckyNumber, LuckyObject)"]:::execution
        INT_ERR["Interpreter Errors"]:::errors
    end

    %% Experimental Sandbox
    SANDBOX["Sandbox (Experimental Lark Grammar)"]:::experimental

    %% Data Flow Arrows
    REPL -->|"sends input"| LEX
    LEX -->|"tokenizes"| PAR
    PAR -->|"builds AST"| INT

    %% Internal Module Relationships
    LEX -->|"uses"| REC
    LEX -->|"reports"| LEX_ERR
    PAR -->|"utilizes"| LOOK
    PAR -->|"reports"| PAR_ERR
    INT -->|"manages"| SYM
    INT -->|"executes"| RUNTIME
    INT -->|"reports"| INT_ERR

    %% Error Propagation Arrows back to REPL
    LEX_ERR -- "error" --> REPL 
    PAR_ERR -- "error" --> REPL 
    INT_ERR -- "error" --> REPL 

    %% Experimental Connection (optional comparison)
    SANDBOX ---|"experiments with"| PAR

    %% Click Events
    click REPL "https://github.com/lucassus/lucky-script/blob/master/src/repl.ts"
    click LEX "https://github.com/lucassus/lucky-script/tree/master/src/Lexer"
    click REC "https://github.com/lucassus/lucky-script/tree/master/src/Lexer/Recognizer"
    click LEX_ERR "https://github.com/lucassus/lucky-script/blob/master/src/Lexer/errors.ts"
    click PAR "https://github.com/lucassus/lucky-script/tree/master/src/Parser"
    click LOOK "https://github.com/lucassus/lucky-script/blob/master/src/Parser/AstNode.ts"
    click PAR_ERR "https://github.com/lucassus/lucky-script/blob/master/src/Parser/errors.ts"
    click INT "https://github.com/lucassus/lucky-script/tree/master/src/Interpreter"
    click SYM "https://github.com/lucassus/lucky-script/blob/master/src/Interpreter/SymbolTable.ts"
    click INT_ERR "https://github.com/lucassus/lucky-script/blob/master/src/Interpreter/errors.ts"
    click RUNTIME "https://github.com/lucassus/lucky-script/tree/master/src/Interpreter/objects"
    click SANDBOX "https://github.com/lucassus/lucky-script/tree/master/lark-sandbox"

    %% Styles
    classDef input fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef analysis fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef execution fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef errors fill:#FFC107,stroke:#000,stroke-width:1px;
    classDef experimental fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
