# kusumotolab/lgmatcher architecture

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

- Interactive diagram: https://gitdiagram.com/kusumotolab/lgmatcher
- Repository: https://github.com/kusumotolab/lgmatcher

## Overview

##### Project type and purpose
- This is a Java library (LGMatcher) that provides a line-based matching algorithm built on top of GumTree’s AST diff engine.
- Its purpose is to expose a Matcher API (`LGMatcher.create(...)`) that takes source/destination code content, their parsed ASTs, and initial mappings, then produces line-level diffs and match information.

##### File structure
- Top-level:
- build.gradle, settings.gradle, Gradle wrapper → standard Java/Gradle build
- src/main/java/com/github/kusumotolab/lgmatcher → core library code
- example/LGMatcherSample → sample application demonstrating usage
- Core packages:
- FilePosConverter.java → converts GumTree node positions into file offsets
- LGMatcher.java → factory for the Matcher instance
- LineMatcher.java → orchestrates the matching pipeline
- MayersDiff.java (in line subpackage) → implements the Myers diff algorithm on line sequences
- entity subpackage → data classes: LineDiff, LineMatch, MatchInformation, Range
- No UI or network components; this is a “library + example app” structure.

##### Key README insights
- The only external runtime dependency is GumTree (for AST parsing/diffing).
- Usage is via a single static factory method.

1. Example App (LGMatcherSample)
2. LGMatcher Library
3. GumTree Engine (external dependency)
4. Output Entities (LineDiff, LineMatch, MatchInformation)
- Example App → calls → LGMatcher.create(srcContent, dstContent, srcTree, dstTree, mappings)
- LGMatcher Library → invokes → GumTree Engine (for AST parsing & initial mappings)
- LGMatcher Library internal pipeline:
‑ FilePosConverter
‑ LineMatcher
‑ MayersDiff
- LineMatcher → produces → Entities
- Entities → returned → Example App
c. Architectural patterns / principles:
- Layered pipeline: input conversion → matching algorithm → entity construction
- Separation of concerns: conversion, matching logic, data representation
- Dependency inversion: core algorithm depends on abstract mappings from GumTree
d. Key technologies:
- Java 8+
- Gradle build system
- GumTree (AST diff)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Example App"
        App["App (LGMatcherSample)"]:::example
    end

    subgraph "LGMatcher Library"
        LGMatcher["LGMatcher (Entry Point)"]:::library
        FilePosConverter["FilePosConverter"]:::library
        LineMatcher["LineMatcher"]:::library
        MayersDiff["MayersDiff"]:::library
    end

    subgraph "Output Entities"
        LineDiff["LineDiff"]:::entity
        LineMatch["LineMatch"]:::entity
        MatchInformation["MatchInformation"]:::entity
        Range["Range"]:::entity
    end

    GumTree["GumTree Engine"]:::external

    subgraph "Build Configuration"
        buildGradle["build.gradle"]:::external
        settings["settings.gradle"]:::external
        gradleWrapper["gradle/wrapper"]:::external
    end

    App -->|"calls LGMatcher.create(srcContent, dstContent, srcTree, dstTree, mappings)"| LGMatcher
    LGMatcher -->|"invokes AST parsing & mappings"| GumTree
    LGMatcher -->|"converts positions"| FilePosConverter
    FilePosConverter -->|"file offsets"| LineMatcher
    LineMatcher -->|"calls diff algorithm"| MayersDiff
    MayersDiff -->|"diff results"| LineMatcher
    LineMatcher -->|"produces entities"| LineDiff
    LineMatcher -->|"produces entities"| LineMatch
    LineMatcher -->|"produces entities"| MatchInformation
    LineMatcher -->|"produces entities"| Range
    LineDiff -->|"returned to App"| App
    LineMatch -->|"returned to App"| App
    MatchInformation -->|"returned to App"| App
    Range -->|"returned to App"| App

    click App "https://github.com/kusumotolab/lgmatcher/blob/master/example/LGMatcherSample/src/main/java/com/github/kusumotolab/App.java"
    click LGMatcher "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/LGMatcher.java"
    click FilePosConverter "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/FilePosConverter.java"
    click LineMatcher "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/LineMatcher.java"
    click MayersDiff "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/line/MayersDiff.java"
    click LineDiff "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/line/entity/LineDiff.java"
    click LineMatch "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/line/entity/LineMatch.java"
    click MatchInformation "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/line/entity/MatchInformation.java"
    click Range "https://github.com/kusumotolab/lgmatcher/blob/master/src/main/java/com/github/kusumotolab/lgmatcher/line/entity/Range.java"
    click buildGradle "https://github.com/kusumotolab/lgmatcher/blob/master/build.gradle"
    click settings "https://github.com/kusumotolab/lgmatcher/blob/master/settings.gradle"
    click gradleWrapper "https://github.com/kusumotolab/lgmatcher/tree/master/gradle/wrapper/"

    classDef example fill:#D6EAF8,stroke:#3498DB,stroke-width:1px
    classDef library fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef external fill:#D5D8DC,stroke:#7F8C8D,stroke-width:1px
    classDef entity fill:#FCF3CF,stroke:#F1C40F,stroke-width:1px
```
