# xhd2015/xgo architecture

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

- Interactive diagram: https://gitdiagram.com/xhd2015/xgo
- Repository: https://github.com/xhd2015/xgo

## Overview

Based on our analysis of the file tree and README, the “xgo” project is a specialized Go tool that provides “all-in-one” test utilities for monkey patching, function interception (trap), trace (stack visualization), and incremental coverage. In other words, it is a command‐line tool with multiple subcommands (e.g., xgo, exec_tool, trace, test explorer) that preprocesses Go source code (via IR rewriting) to inject mocking, tracing, and trap functionalities. The project includes an extensive runtime library “runtime” (with subpackages like runtime/mock, runtime/trap, and runtime/trace), patch modules (for IR rewriting), and support utilities for transformation, file copying, debugging, and more.

##### Main Components
- CLI & Command Modules: This includes the main executable under cmd/xgo and its related subcommands (such as exec_tool, go-tool-test-explorer, trace, and upgrade). These commands serve as the user interface and entry points.
- Preprocessing & Patch Engine: The “patch” directory and associated IR rewriting code are core to how xgo intercepts and rewrites Go code. This subsystem intercepts the compilation process and applies monkey patching, trap injection, and trace instrumentation.
- Runtime & Interception Libraries: The “runtime” folder (with subpackages like runtime/mock, runtime/trace, runtime/trap) contains the logic for mocking functions, intercepting function calls (traps), and capturing stack traces. These components are tightly integrated with the preprocessor.
- Support Libraries: Various “support” modules (such as support/transform, support/goinfo, support/fileutil) assist with string manipulation, file copy, debugging, and other auxiliary tasks.
- Developer & CI Integration: The project includes GitHub workflows (under .github/workflows) and scripts (script/*) for building, releasing, and installing. This represents the integration point with CI/CD pipelines.

##### Relationships & Data Flows
- Users invoke the CLI (xgo) to perform tasks such as testing, building, or running the test explorer.
- The CLI triggers the preprocessor which interprets and rewrites the Go source code using the patch subsystem. This step modifies the Intermediate Representation (IR) before handing off to the standard Go toolchain.
- Once the code is modified, the runtime libraries (trap, mock, trace) are active and intercept function calls during execution.
- For testing, the xgo test command uses these runtime modules to control and observe the behavior of functions (patch/mocking) and to capture stack traces (trace) that are later displayed via a web UI (test explorer) or incremental coverage tool.
- The support libraries provide utilities that are used by both the preprocessor and the runtime modules.
- External dependencies and vendored packages (found under cmd/xgo/internal/vendir) are used to provide compatibility and extended functionality.

##### Architectural Patterns & Design Principles
- Modular/Layered Architecture: The separation between interface (CLI commands), core preprocessing logic, runtime interception libraries, and support utilities.
- IR Rewriting: Instead of relying on low-level ASM, xgo leverages a stable IR rewriting technique during the build process.
- Extensibility & Testability: xgo is designed to work as a transparent preprocessor for “go test” and “go run,” supporting features like per-instance mocking and incremental coverage without intrusive changes to the source code.

##### Relevant Technologies & Frameworks
- Go (golang) itself as the base language.
- GitHub Actions for CI/CD (visible under .github/workflows).
- Web technologies for the test explorer UI (HTML, JavaScript, CSS under cmd/xgo/test-explorer and doc/img).
- Standard Go toolchain integration (the tool calls and then wraps “go build,” “go test,” etc.)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User & CLI Layer"
        U("User Terminal"):::external
        CLI["xgo CLI (cmd/xgo)"]:::cli
        EXEC["exec_tool (cmd/exec_tool)"]:::cli
        TRACECMD["trace (cmd/trace)"]:::cli
        TESTEX["Test Explorer (cmd/go-tool-test-explorer)"]:::cli
        COVER["Coverage (cmd/go-tool-coverage)"]:::cli
    end

    subgraph "Preprocessing & Patch Engine"
        PE["Patch Engine<br/>(IR Rewriting)"]:::preproc
        PATCH1["Patch: patch.go"]:::preproc
        PATCH2["Patch: patch_compiler.go"]:::preproc
        PATCH3["Patch: patch_reflect.go"]:::preproc
    end

    subgraph "Runtime Interception Core"
        RC["Runtime Core (runtime)"]:::runtime
        MOCK["Mock Module<br/>(runtime/mock)"]:::runtime
        TRAP["Trap Module<br/>(runtime/trap)"]:::runtime
        TRACE["Trace Module<br/>(runtime/trace)"]:::runtime
    end

    subgraph "Support Libraries"
        SUP["Support Utilities (support)"]:::support
        TRANS["Transform (support/transform)"]:::support
        FILEUTIL["FileUtil (support/fileutil)"]:::support
        DEBUG["Debug (support/debug)"]:::support
        GOINFO["GoInfo (support/goinfo)"]:::support
    end

    subgraph "Developer & CI Integration"
        CI["CI/CD Pipeline (.github/workflows)"]:::cicd
        SCRIPTS["Build Scripts (script)"]:::cicd
        VEND["Vendored Dependencies<br/>(internal/vendir)"]:::cicd
    end

    subgraph "External Interfaces"
        TOOLCHAIN(("Go Toolchain")):::external
        TESTUI(("Test Explorer UI")):::external
    end

    %% Flow Connections
    U --> CLI
    CLI --> EXEC
    CLI --> TRACECMD
    CLI --> TESTEX
    CLI --> COVER

    CLI -->|"sends_source"| PE
    PE -->|"IR_modified_code"| RC
    RC -->|"calls_build"| TOOLCHAIN
    TRACE -->|"captures_stack"| TESTUI

    %% Support influences
    SUP ---|"supports"| PE
    SUP ---|"supports"| RC

    %% CI/CD Integration
    CI --- CLI
    CI --- SCRIPTS
    SCRIPTS --> CLI

    %% Vendored Dependencies connection
    VEND --- CLI

    %% Internal Runtime Linking
    RC --> MOCK
    RC --> TRAP
    RC --> TRACE

    %% Preprocessing internal details
    PE --> PATCH1
    PE --> PATCH2
    PE --> PATCH3

    %% Click Events
    click CLI "https://github.com/xhd2015/xgo/tree/master/cmd/xgo"
    click EXEC "https://github.com/xhd2015/xgo/tree/master/cmd/exec_tool"
    click TRACECMD "https://github.com/xhd2015/xgo/tree/master/cmd/trace"
    click TESTEX "https://github.com/xhd2015/xgo/tree/master/cmd/go-tool-test-explorer"
    click COVER "https://github.com/xhd2015/xgo/tree/master/cmd/go-tool-coverage"

    click PE "https://github.com/xhd2015/xgo/tree/master/patch"
    click PATCH1 "https://github.com/xhd2015/xgo/blob/master/cmd/xgo/patch.go"
    click PATCH2 "https://github.com/xhd2015/xgo/blob/master/cmd/xgo/patch_compiler.go"
    click PATCH3 "https://github.com/xhd2015/xgo/blob/master/cmd/xgo/patch_reflect.go"

    click RC "https://github.com/xhd2015/xgo/tree/master/runtime"
    click MOCK "https://github.com/xhd2015/xgo/tree/master/runtime/mock"
    click TRAP "https://github.com/xhd2015/xgo/tree/master/runtime/trap"
    click TRACE "https://github.com/xhd2015/xgo/tree/master/runtime/trace"

    click SUP "https://github.com/xhd2015/xgo/tree/master/support"
    click TRANS "https://github.com/xhd2015/xgo/tree/master/support/transform"
    click FILEUTIL "https://github.com/xhd2015/xgo/tree/master/support/fileutil"
    click DEBUG "https://github.com/xhd2015/xgo/tree/master/support/debug"
    click GOINFO "https://github.com/xhd2015/xgo/tree/master/support/goinfo"

    click CI "https://github.com/xhd2015/xgo/tree/master/.github/workflows"
    click SCRIPTS "https://github.com/xhd2015/xgo/tree/master/script"
    click VEND "https://github.com/xhd2015/xgo/tree/master/cmd/xgo/internal/vendir"

    %% Style Definitions
    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef preproc fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef runtime fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef support fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef cicd fill:#E8DAEF,stroke:#76448A,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#239B56,stroke-width:2px;
```
