# es-meta/esmeta architecture

> Architecture diagram of the GitHub repository es-meta/esmeta, 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/es-meta/esmeta
- Repository: https://github.com/es-meta/esmeta

## Overview

##### Project Type and Purpose
- ESMeta is a specialized framework written in Scala (built with sbt) that “mechanizes” the ECMAScript (JavaScript) specification. Its goal is to extract the specification from ECMA-262, compile that into an intermediate representation (IRES), build control-flow graphs, perform type analysis, and even support features such as a Test262 runner, assertion injection, fuzzing, and an interactive debugger (with a separate client).
- The README indicates that the system supports several commands (extract, compile, build-cfg, tycheck, parse, eval, web, etc.) making it a command-line driven tool with auxiliary web client support.

##### Analyzing the File Structure
- At the top level, you see configuration and build files (e.g., build.sbt, .scalafmt.conf) and directories like “src”, “client”, “project”, “tests”, and “scripts”. These are common to a Scala sbt project.
- The “src/main/scala/esmeta” directory is organized into subpackages (analyzer, cfg, compiler, error, extractor, fuzzer, injector, interpreter, ir, lang, parser, phase, spec, state, test262, ty, util, web, etc.). These represent distinct modules each responsible for a piece of the overall functionality.
- The “client” directory suggests a separate Node project for the web debugger. This module interacts with the backend (running as part of “esmeta web”) to provide an interactive debugging experience through a browser.
- The “tests” directory (with further subdivisions into “scala” and “ir” areas) indicates a robust test suite that interacts with many core components.

##### Main Components Identification
a. Command-Line Interface (CLI) & Command Dispatcher:
- This layer (e.g., esmeta/Command.scala, various command implementations in src/main/scala/esmeta/analyzer/repl/command and similar folders) serves as the entry point. It parses user commands and options (such as “extract”, “compile”, “build-cfg”, “tycheck”, “eval”, “inject”, “fuzz”, “test262-test”).
b. Specification Extraction and Compilation:
- The “extract” process uses the “esmeta/spec” packages to convert ECMAScript specification files (e.g., the local copy “ecma262” or an online spec) into an internal model.
- The “compiler” module (src/main/scala/esmeta/compiler) then compiles this model into an Intermediate Representation (IRES), which is then used by later phases.
c. CFG (Control-Flow Graph) Builder:
- The “cfg” component (in src/main/scala/esmeta/cfg and cfgbuilder subfolders) takes the compiled IR to build control-flow graphs; this diagrammatically represents the semantics of specification algorithms.
d. Type Analysis Engine:
- Located in “ty” and subpackages (also interconnected with “analyzer” and “tychecker” packages), the type analysis component infers and refines types across the specification algorithms.
e. ECMAScript Program Execution & Analysis:
- The “parser”, “interpreter”, “injector”, and “fuzzer” modules enable parsing, executing, assertion injection, and synthesizing JavaScript programs from the specification.
f. Web Debugger and Client Integration:
- The “web” module in src/main/scala/esmeta/web and the “client” (node-based) directory provide an interactive double debugger interface that visualizes specification execution.
g. Supporting Utilities:
- There are several “util” packages across different modules (analyzer/util, cfg/util, etc.) that include shared functionality like graph generation (DotPrinter), JSON protocols, stringifiers, and parsing utilities.
h. Testing & Validation:
- The “tests” directory and the “test262” handling in the README indicate modules for conformance testing using Test262 as well as result logging.

##### Relationships and Interactions
- At the top, the User Interface (CLI commands, Web interface via client) sends commands to the core engine.
- The CLI dispatcher routes commands to the corresponding core modules (extractor → compiler → CFG builder, or tychecker for type analysis).
- Data flows from external ECMAScript/ECMA-262 specification inputs into the Extraction module and then into a sequential pipeline: IR program → CFG → debugger visualization.
- The fuzzer and injector modules take inputs from the core IR and specification models to generate tests or inject assertions.
- The testing components (Test262 runner) interact with the evaluator and interpreter modules.
- Utility modules support all steps by providing logging, graph generation, JSON parsing, etc.

##### Architectural Patterns & Design Principles
- The design reflects modular separation (each functional module in its own package) and follows a pipeline architecture where the output of one module is fed to the next (extraction → compilation → CFG building → further analysis or testing).
- A microservices-like separation is seen between the CLI/backend engine and the client-side web debugger.
- Use of standardized protocols (e.g., JSON) for inter-module data interchange is suggested by the presence of JSONProtocol utilities in many components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    UI("User"):::external

    %% CLI Interface
    subgraph "CLI Interface"
        cli("ESMeta CLI"):::cli
        dispatcher("Command Dispatcher"):::cli
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        spec("Specification Extractor"):::core
        compiler("IR Compiler"):::core
        cfg("CFG Builder"):::core
        tyan("Type Analyzer"):::core
        subgraph "Execution & Analysis"
            parser("Parser"):::core
            interpreter("Interpreter"):::core
            injector("Injector"):::core
            fuzzer("Fuzzer"):::core
        end
    end

    %% Ancillary Modules
    subgraph "Ancillary Modules"
        test262("Test262 Runner"):::anc
        webdbg("Web Debugger & API Server"):::anc
        client("Debugger Client"):::anc
        utils("Utility Modules"):::util
    end

    %% Relationships
    UI -->|"issues_commands"| cli
    cli --> dispatcher
    dispatcher -->|"triggers_extraction"| spec
    spec -->|"generates_IR"| compiler
    compiler -->|"builds_CFG"| cfg
    cfg -->|"analyzes"| tyan
    tyan -->|"feeds"| parser
    parser --> interpreter
    interpreter --> injector
    injector --> fuzzer

    dispatcher -->|"executes_tests"| test262
    dispatcher -->|"launches_web"| webdbg
    webdbg --> client

    %% Utilities support
    tyan -->|"utilizes"| utils

    %% Styles
    classDef cli fill:#b3e5fc,stroke:#0277bd,stroke-width:2px;
    classDef core fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef anc fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef util fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#512da8,stroke-width:2px;

    %% Click Events
    click cli "https://github.com/es-meta/esmeta/blob/main/src/main/scala/esmeta/Command.scala"
    click dispatcher "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/analyzer/repl/command/"
    click spec "https://github.com/es-meta/esmeta/blob/main/src/main/scala/esmeta/extractor/Extractor.scala"
    click compiler "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/compiler/"
    click cfg "https://github.com/es-meta/esmeta/blob/main/src/main/scala/esmeta/cfgbuilder/CFGBuilder.scala"
    click tyan "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/ty/"
    click parser "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/parser/"
    click interpreter "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/interpreter/"
    click injector "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/injector/"
    click fuzzer "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/fuzzer/"
    click test262 "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/test262/"
    click webdbg "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/web/"
    click client "https://github.com/es-meta/esmeta/tree/main/client/"
    click utils "https://github.com/es-meta/esmeta/tree/main/src/main/scala/esmeta/util/"
```
