# kmura88/sbfl_command architecture

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

- Interactive diagram: https://gitdiagram.com/kmura88/sbfl_command
- Repository: https://github.com/kmura88/sbfl_command

## Overview

##### Project Type and Purpose
- This is an open-source CLI tool for Java Suspicious Behavior Fault Localization (SBFL).
- It orchestrates Java test execution (JUnit3/4), collects coverage via JaCoCo, converts it to XML, then runs Python-based analysis to compute fault‐localization metrics (e.g., Ochiai, Tarantula).

##### High-Level Architecture Components
a. CLI Wrapper Scripts (.cmd)
- SBFL-JUnit3.cmd, SBFL-JUnit4.cmd, xml_maker_junit3.cmd, xml_maker_junit4.cmd
- Accept user arguments (test class, target class), set up environment, invoke downstream steps.
b. Java Execution Layer
- Classes in `classes/` (compiled output) and source in `src/`:
- MethodParserAndRunner(.java) & its JUnit3 variant: extract @Test methods from test classes
- RunSingleTest(.java) & its JUnit3 variant: invoke individual test methods via JUnitCore
- Relies on JUnit jars (`lib/junit/…`) on the classpath.
c. Coverage Collector (JaCoCo)
- Agent jars in `lib/jacoco/` instrument bytecode at runtime
- Generates `.exec` files (one per test‐method).
d. XML Generator
- XML conversion driven by xml_maker_*.cmd scripts
- Processes each `.exec` into an XML report describing line coverage & test pass/fail.
e. Python Analysis Layer (in `lib/`)
- XmlAnalyzer.py – filters out SBFL tool classes + test classes, transforms XML to boolean coverage per line
- LineExecutionCounter.py – tallies execution counts from XML reports
- SBFL_base.py – computes nf (not failed hits), ef (executed failed hits), np, ep, writes raw results to CSV
- SBFL_Ochiai.py & SBFL_Tarantula.py – extend SBFL_base with specific suspiciousness formulas
f. File System / Data Stores
- Input: `classes/` (compiled .class files), `src/` (source .java for recompile)
- Intermediate: per‐test `.exec` files, per‐test XML coverage files
- Output: CSV ranking lines by suspiciousness

##### Component Interactions & Data Flow
1) User runs `SBFL-JUnit4.cmd testClass targetClass`
2) CLI script checks args, ensures `classes/` and `src/` are populated
3) MethodParserAndRunner parses test class for method names → invokes `xml_maker_junit4.cmd` per method
4) xml_maker:
- Launches `java -javaagent:jacocoagent.jar … RunSingleTest testClass#method`
- Produces `.exec` via JaCoCo
- Runs JaCoCo CLI to emit XML per `.exec`
5) For each XML: Python XmlAnalyzer filters & converts to boolean coverage → LineExecutionCounter tallies
6) SBFL_base collects nf, ef, np, ep → writes intermediate CSV
7) SBFL_Ochiai and SBFL_Tarantula compute suspiciousness → augment final CSV output

##### Architectural Patterns & Design Principles
- Pipeline architecture: sequential transformation of data (test definitions → exec → XML → counts → metrics).
- Separation of concerns:
- CLI orchestration (.cmd)
- Java for test execution & coverage capture
- Python for data parsing & metric computation
- Extensibility points: adding new SBFL metrics by subclassing SBFL_base, supporting JUnit5 by adding new runner classes.

##### Detailed Elements to Capture
- .cmd scripts as entry points
- Distinct Java classes for test parsing vs. test execution
- JaCoCo agent injection and its output artifacts
- XML conversion step and filtering logic (ignoring tool classes/tests)
- Python modules with clear inheritance from SBFL_base
- Final CSV generation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Class Definitions
    classDef cli fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef java fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef python fill:#ffddb3,stroke:#333,stroke-width:1px
    classDef storage fill:#e0e0e0,stroke:#333,stroke-width:1px

    %% CLI Wrapper Layer
    subgraph "CLI Wrapper" 
        direction TB
        CLI3["SBFL-JUnit3.cmd"]:::cli
        CLI4["SBFL-JUnit4.cmd"]:::cli
    end

    %% Java Execution Layer
    subgraph "Java Execution Layer"
        direction TB
        MP4["MethodParserAndRunner.java"]:::java
        MP3["MethodParserAndRunnerForJUnit3.java"]:::java
        RS4["RunSingleTest.java"]:::java
        RS3["RunSingleTestForJUnit3.java"]:::java
        COMP["classes/"]:::storage
    end

    %% Coverage Collector (JaCoCo)
    subgraph "JaCoCo Coverage Collector"
        direction TB
        AGENT["jacocoagent.jar"]:::storage
        ANT["jacocoant.jar"]:::storage
        CLIJ["jacococli.jar"]:::storage
    end

    %% XML Generator
    subgraph "XML Generator"
        direction TB
        XML3["xml_maker_junit3.cmd"]:::cli
        XML4["xml_maker_junit4.cmd"]:::cli
    end

    %% Python Analysis Layer
    subgraph "Python Analysis"
        direction TB
        XAN["XmlAnalyzer.py"]:::python
        LEC["LineExecutionCounter.py"]:::python
        SB["SBFL_base.py"]:::python
        OCH["SBFL_Ochiai.py"]:::python
        TAR["SBFL_Tarantula.py"]:::python
    end

    %% File System / Data Stores
    subgraph "File System / Data Stores"
        direction TB
        SRC["src/"]:::storage
        JUNITLIB["lib/junit jars"]:::storage
        CFG["lib/config.cmd"]:::storage
        EXEC[".exec files"]:::storage
        XMLREP["XML reports"]:::storage
        CSV["Final CSV output"]:::storage
    end

    %% Connections
    CLI3 -->|runs parser| MP3
    CLI4 -->|runs parser| MP4
    MP3 -->|invokes runner| RS3
    MP4 -->|invokes runner| RS4
    RS3 -->|reads classes| COMP
    RS4 -->|reads classes| COMP

    RS3 -->|instrument with agent| AGENT
    RS4 -->|instrument with agent| AGENT
    AGENT -->|generates| EXEC
    EXEC -->|processed by| CLIJ
    EXEC -->|via XML scripts| XML3
    EXEC -->|via XML scripts| XML4
    AGENT -->|ant tasks| ANT

    XML3 -->|produces| XMLREP
    XML4 -->|produces| XMLREP

    XMLREP -->|parse/filter| XAN
    XAN -->|boolean coverage| LEC
    LEC -->|counts| SB
    SB -->|compute metric| OCH
    SB -->|compute metric| TAR
    OCH -->|writes| CSV
    TAR -->|writes| CSV

    SRC --> MP3
    SRC --> MP4
    COMP --> RS3
    COMP --> RS4

    JUNITLIB --> MP3
    JUNITLIB --> MP4

    CFG --> XML3
    CFG --> XML4

    %% Click Events
    click CLI3 "https://github.com/kmura88/sbfl_command/blob/main//SBFL-Junit3.cmd"
    click CLI4 "https://github.com/kmura88/sbfl_command/blob/main//SBFL-Junit4.cmd"
    click XML3 "https://github.com/kmura88/sbfl_command/blob/main//lib/xml_maker_junit3.cmd"
    click XML4 "https://github.com/kmura88/sbfl_command/blob/main//lib/xml_maker_junit4.cmd"
    click MP4 "https://github.com/kmura88/sbfl_command/blob/main/src/MethodParserAndRunner.java"
    click MP3 "https://github.com/kmura88/sbfl_command/blob/main/src/MethodParserAndRunnerForJUnit3.java"
    click RS4 "https://github.com/kmura88/sbfl_command/blob/main/src/RunSingleTest.java"
    click RS3 "https://github.com/kmura88/sbfl_command/blob/main/src/RunSingleTestForJUnit3.java"
    click COMP "https://github.com/kmura88/sbfl_command/tree/main/classes/"
    click AGENT "https://github.com/kmura88/sbfl_command/blob/main/lib/jacoco/jacocoagent.jar"
    click CLIJ "https://github.com/kmura88/sbfl_command/blob/main/lib/jacoco/jacococli.jar"
    click XAN "https://github.com/kmura88/sbfl_command/blob/main/lib/XmlAnalyzer.py"
    click LEC "https://github.com/kmura88/sbfl_command/blob/main/lib/LineExecutionCounter.py"
    click SB "https://github.com/kmura88/sbfl_command/blob/main/lib/SBFL_base.py"
    click OCH "https://github.com/kmura88/sbfl_command/blob/main/lib/SBFL_Ochiai.py"
    click TAR "https://github.com/kmura88/sbfl_command/blob/main/lib/SBFL_Tarantula.py"
```
