# gvvaughan/specl architecture

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

- Interactive diagram: https://gitdiagram.com/gvvaughan/specl
- Repository: https://github.com/gvvaughan/specl

## Overview

##### Main Components

a. Core Testing Framework
- Main execution flow components (runner, loader, matchers)
- Sandbox environment for test isolation

b. Input/Output Components
- YAML spec files input
- Multiple formatter outputs (progress, report, TAP)
- Command-line interface

c. Support Systems
- Shell execution environment
- Expectation handling
- Utility functions

##### Component Relationships

**[YAML Spec Files] → [Loader] → [Runner] → [Formatters]**
- ↓          ↓            ↑
- [Sandbox] → [Matchers] → [Expect]
- ↓          ↓
- [Shell]    [Utilities]

##### Specific Implementation Details

a. Test Execution Flow:
- How specs flow from YAML files through the system
- Sandbox isolation boundary
- Formatter output options

b. Core Components:
- Loader (lib/specl/loader.lua): YAML spec file parsing
- Runner (lib/specl/runner.lua): Test execution engine
- Matchers (lib/specl/matchers.lua): Assertion system
- Expect (lib/specl/expect.lua): Expectation handling

c. Support Systems:
- Shell (lib/specl/shell.lua): Command execution
- Sandbox (lib/specl/sandbox.lua): Test isolation
- Utilities (lib/specl/util.lua): Helper functions

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Input
        YAML["YAML Spec Files"]:::input
    end

    subgraph Core["Core Testing Framework"]
        Loader["Spec Loader"]:::core
        Runner["Test Runner"]:::core
        Main["Main Execution"]:::core
        Version["Version Manager"]:::core
        Compat["Compatibility Layer"]:::core
    end

    subgraph Testing["Testing Environment"]
        Sandbox["Sandbox Environment"]:::isolation
        Shell["Shell Execution"]:::support
        Matchers["Matchers System"]:::core
        Expect["Expectation Handler"]:::core
        Utils["Utility Functions"]:::support
        Color["Color Output"]:::support
    end

    subgraph Output["Output Layer"]
        CLI["Command Line Interface"]:::output
        subgraph Formatters["Formatters"]
            Progress["Progress Formatter"]:::formatter
            Report["Report Formatter"]:::formatter
            TAP["TAP Formatter"]:::formatter
        end
    end

    %% Relationships
    YAML --> Loader
    Loader --> Runner
    Runner --> Main
    Main --> Formatters
    Runner --> Sandbox
    Sandbox --> Shell
    Runner --> Matchers
    Matchers --> Expect
    Utils --> Runner
    Utils --> Loader
    Color --> Formatters
    Version --> Main
    Compat --> Main
    Formatters --> CLI

    %% Click Events
    click Runner "https://github.com/gvvaughan/specl/blob/master/lib/specl/runner.lua"
    click Loader "https://github.com/gvvaughan/specl/blob/master/lib/specl/loader.lua"
    click Matchers "https://github.com/gvvaughan/specl/blob/master/lib/specl/matchers.lua"
    click Sandbox "https://github.com/gvvaughan/specl/blob/master/lib/specl/sandbox.lua"
    click Shell "https://github.com/gvvaughan/specl/blob/master/lib/specl/shell.lua"
    click Expect "https://github.com/gvvaughan/specl/blob/master/lib/specl/expect.lua"
    click Utils "https://github.com/gvvaughan/specl/blob/master/lib/specl/util.lua"
    click Progress "https://github.com/gvvaughan/specl/blob/master/lib/specl/formatter/progress.lua"
    click Report "https://github.com/gvvaughan/specl/blob/master/lib/specl/formatter/report.lua"
    click TAP "https://github.com/gvvaughan/specl/blob/master/lib/specl/formatter/tap.lua"
    click CLI "https://github.com/gvvaughan/specl/tree/master/bin/specl"
    click YAML "https://github.com/gvvaughan/specl/blob/master/spec/*.yaml"
    click Main "https://github.com/gvvaughan/specl/blob/master/lib/specl/main.lua"
    click Color "https://github.com/gvvaughan/specl/blob/master/lib/specl/color.lua"
    click Version "https://github.com/gvvaughan/specl/blob/master/lib/specl/version.lua.in"
    click Compat "https://github.com/gvvaughan/specl/blob/master/lib/specl/compat.lua"

    %% Styles
    classDef core fill:#2374ab,stroke:#000,color:#fff
    classDef input fill:#57a773,stroke:#000,color:#fff
    classDef output fill:#57a773,stroke:#000,color:#fff
    classDef support fill:#ffc857,stroke:#000
    classDef isolation fill:#ef476f,stroke:#000,color:#fff
    classDef formatter fill:#06d6a0,stroke:#000

    %% Legend
    subgraph Legend
        L1["Core Component"]:::core
        L2["Input/Output"]:::input
        L3["Support Utility"]:::support
        L4["Isolation Boundary"]:::isolation
        L5["Formatter"]:::formatter
    end
```
