# saeg/asm-defuse architecture

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

- Interactive diagram: https://gitdiagram.com/saeg/asm-defuse
- Repository: https://github.com/saeg/asm-defuse

## Overview

Based on our review of the file tree and README, this project is a Java-based analysis library that extends the ASM bytecode manipulation framework with control- and data-flow analysis capabilities. In other words, it is not a standalone full-stack application but a tool that provides detailed def-use (definition/usage) analysis via algorithms wrapped around ASM’s APIs.

##### Main Components
- ASM Integration Layer – Though ASM itself is external, it is central because this tool extends its analysis API.
- Control-Flow Analysis Component – Represented by the FlowAnalyzer class that computes successors, predecessors, basic blocks, and leaders.
- Data-Flow Analysis Component – Implemented by the DefUseAnalyzer and the related DefUseFrame classes that capture definitions and uses at each instruction.
- Definition-Use Chain Computation – Captured by classes like DefUseChain, DefUseChainSearch (and its concrete implementation, e.g., DepthFirstDefUseChainSearch) and DefUseInterpreter.
- Utility and Data Structures – Various helper classes (e.g., ArrayRef, ArrayValue, Variable, Value, ValueHolder, etc.) support the analysis.
- Testing and Validation – Separate packages (in src/test) ensure integration-level tests and individual unit tests are available.

##### Relationships and Interactions
- From FlowAnalyzer, show the derivation of the successors and predecessors arrays, basic blocks, and leaders – these outputs become inputs to later processing stages.
- How DefUseAnalyzer consumes the output from FlowAnalyzer (or uses its own mechanisms) and works in conjunction with DefUseInterpreter for deeper analysis.

##### Architectural Patterns and Design Principles
- The design follows a layered approach. The lower layer is the ASM integration while above it lie analyzers that process control flow and data flow.
- There is a clear separation of concerns: one class/module focuses on control flow, another on data flow, and a subsequent one on chain analysis.
- Dependency inversion can be noted – for instance, the DefUseAnalyzer abstracts underlying interpreter and flow-analysis details, making it adaptable.

##### Relevant Technologies and Dependencies
- Java as the programming language (with a minimum version requirement of Java 6).
- Maven for project build/management (as indicated by pom.xml, mvnw, etc.).
- The ASM framework as a dependency and underlying library.
- Testing frameworks integrated through the Maven configuration (observed in the src/test directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global external node
    ASM_API["MethodNode (ASM API)"]:::external
    
    %% ASM Integration Layer
    ASM_Integration["ASM Integration Layer"]:::external

    %% Core Analysis Subgraph
    subgraph "Core Analysis"
        FlowAnalyzer["FlowAnalyzer: Computes Control Flow"]:::control
        DefUseAnalyzer["DefUseAnalyzer: Gathers Def/Use Info"]:::data
        DefUseFrame["DefUseFrame (Execution Frame)"]:::data
        DefUseInterpreter["DefUseInterpreter: Interprets Instructions"]:::interpreter
    end

    %% Def-Use Chain Computation Subgraph
    subgraph "Def-Use Chain Computation"
        DefUseChain["DefUseChain (Chain Container)"]:::chain
        DefUseChainSearch["DefUseChainSearch (Interface)"]:::chain
        DepthFirstDefUseChainSearch["DepthFirstDefUseChainSearch (Implementation)"]:::chain
    end

    %% Utility & Data Structures Subgraph
    subgraph "Utility & Data Structures"
        ArrayRef["ArrayRef"]:::utility
        ArrayValue["ArrayValue"]:::utility
        CacheableVariablesValue["CacheableVariablesValue"]:::utility
        Field["Field"]:::utility
        IntList["IntList"]:::utility
        Invoke["Invoke"]:::utility
        Local["Local"]:::utility
        Merge["Merge"]:::utility
        ObjectField["ObjectField"]:::utility
        ObjectRef["ObjectRef"]:::utility
        PathAnalyzer["PathAnalyzer"]:::utility
        StaticField["StaticField"]:::utility
        Value["Value"]:::utility
        ValueHolder["ValueHolder"]:::utility
        Variable["Variable"]:::utility
        VariableImpl["VariableImpl"]:::utility
    end

    %% Testing and Validation Subgraph
    subgraph "Testing and Validation"
        UnitTests["Unit Tests"]:::test
        IntegrationTests["Integration Tests"]:::test
        ValidationTests["Validation Tests"]:::test
    end

    %% Relationships
    ASM_API --> ASM_Integration
    ASM_Integration --> FlowAnalyzer
    ASM_Integration --> DefUseAnalyzer
    ASM_API -->|"Input: MethodNode"| FlowAnalyzer
    ASM_API -->|"Input: MethodNode"| DefUseAnalyzer
    FlowAnalyzer -->|"output:controlflow"| DefUseAnalyzer
    DefUseAnalyzer -->|"dataflow"| DefUseInterpreter
    DefUseInterpreter -->|"interprets"| DefUseChainSearch
    DefUseChainSearch -->|"searches"| DepthFirstDefUseChainSearch
    DepthFirstDefUseChainSearch -->|"assembles"| DefUseChain

    %% Testing interactions (dashed arrows)
    UnitTests -.->|"validates"| FlowAnalyzer
    UnitTests -.->|"validates"| DefUseAnalyzer
    IntegrationTests -.->|"validates"| DefUseChain
    ValidationTests -.->|"validates"| DefUseInterpreter

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef control fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef data fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef interpreter fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef chain fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef test fill:#E6E6FA,stroke:#000,stroke-width:2px;

    %% Click Events for Core Components
    click ASM_Integration "https://github.com/saeg/asm-defuse/tree/master/src/main/java/br/usp/each/saeg/asm"
    click FlowAnalyzer "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/FlowAnalyzer.java"
    click DefUseAnalyzer "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/DefUseAnalyzer.java"
    click DefUseFrame "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/DefUseFrame.java"
    click DefUseInterpreter "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/DefUseInterpreter.java"
    click DefUseChain "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/DefUseChain.java"
    click DefUseChainSearch "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/DefUseChainSearch.java"
    click DepthFirstDefUseChainSearch "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/DepthFirstDefUseChainSearch.java"

    %% Click Events for Utility and Data Structures
    click ArrayRef "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/ArrayRef.java"
    click ArrayValue "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/ArrayValue.java"
    click CacheableVariablesValue "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/CacheableVariablesValue.java"
    click Field "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/Field.java"
    click IntList "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/IntList.java"
    click Invoke "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/Invoke.java"
    click Local "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/Local.java"
    click Merge "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/Merge.java"
    click ObjectField "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/ObjectField.java"
    click ObjectRef "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/ObjectRef.java"
    click PathAnalyzer "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/PathAnalyzer.java"
    click StaticField "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/StaticField.java"
    click Value "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/Value.java"
    click ValueHolder "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/ValueHolder.java"
    click Variable "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/Variable.java"
    click VariableImpl "https://github.com/saeg/asm-defuse/blob/master/src/main/java/br/usp/each/saeg/asm/defuse/VariableImpl.java"

    %% Click Events for Testing and Validation
    click UnitTests "https://github.com/saeg/asm-defuse/tree/master/src/test/java/br/usp/each/saeg/asm/defuse"
    click IntegrationTests "https://github.com/saeg/asm-defuse/tree/master/src/test/java/br/usp/each/saeg/asm/defuse/integration"
    click ValidationTests "https://github.com/saeg/asm-defuse/tree/master/src/test/java/br/usp/each/saeg/asm/defuse/validation"
```
