# quanxiny/tc-sosp-code-clone-explanation architecture

> Architecture diagram of the GitHub repository quanxiny/tc-sosp-code-clone-explanation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quanxiny/tc-sosp-code-clone-explanation
- Repository: https://github.com/quanxiny/tc-sosp-code-clone-explanation

## Overview

TC-SOSP is a research codebase for evaluating task-conditioned semantic subgraph-pair explanations of code-clone predictions. The main workflow is a researcher invoking the CLI with a resolved experiment configuration; experiment runners load graph pairs and a predictor, generate explanations, and record faithfulness, stability, or transformation-truth measurements. Separate builders create alpha-renaming/dead-code truth and transformed negative-pair truth, while aggregation modules summarize study records. The graph follows documented capabilities and SOURCE INDEX references; unsampled implementation details and artifact wiring are not inferred.

Main entry points: [`scripts/explanation_runner.py`](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/explanation_runner.py) (Pair explainers), [`scripts/negative_pair_truth_runner.py`](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/negative_pair_truth_runner.py) (Negative-pair evaluator), [`scripts/truth_explanation_runner.py`](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/truth_explanation_runner.py) (Truth evaluator), [`scripts/contrastive_runner.py`](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/contrastive_runner.py) (Graph-pair runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Experiment entry"]
  node_cli["Research CLI<br/>[research_cli.py]"]
  node_config["Config resolver<br/>[configlib.py]"]
end

subgraph group_explain["Explanation evaluation"]
  node_contrastive["Graph-pair runner"]
  node_explainer["Pair explainers"]
  node_gcj["GCJ reproduction<br/>[reproduce_gcj.py]"]
  node_gcj_batch["Batched GCJ runner"]
end

subgraph group_truth["Truth construction"]
  node_truth_runner["Truth evaluator"]
  node_negative_runner["Negative-pair evaluator"]
  node_truth_builder["Transformation truth builder"]
  node_negative_builder["Negative truth builder"]
  node_truth_data["Transformation bundles"]
end

subgraph group_analysis["Study analysis"]
  node_optimal_stats["Optimal-study analysis"]
  node_seed_stats["Seed analysis"]
  node_truth_stats["Truth statistics"]
  node_studies["Study records"]
end

node_researcher(("Researcher"))

node_researcher -->|"invokes"| node_cli
node_cli -->|"resolves"| node_config
node_cli -->|"dispatches"| node_contrastive
node_cli -->|"dispatches"| node_explainer
node_cli -->|"dispatches"| node_truth_runner
node_cli -->|"dispatches"| node_negative_runner
node_contrastive -->|"uses"| node_config
node_contrastive -->|"loads predictor"| node_gcj
node_contrastive -->|"loads predictor"| node_gcj_batch
node_explainer -->|"uses"| node_config
node_explainer -->|"reuses graph model"| node_contrastive
node_explainer -->|"loads predictor"| node_gcj
node_explainer -->|"loads predictor"| node_gcj_batch
node_truth_runner -->|"uses"| node_config
node_truth_runner -->|"reuses graph model"| node_contrastive
node_truth_runner -->|"calls explainers"| node_explainer
node_truth_runner -->|"loads predictor"| node_gcj_batch
node_negative_runner -->|"uses"| node_config
node_negative_runner -->|"reuses graph model"| node_contrastive
node_negative_runner -->|"calls explainers"| node_explainer
node_negative_runner -->|"reuses truth methods"| node_truth_runner
node_negative_runner -->|"loads predictor"| node_gcj_batch
node_truth_builder -.->|"creates bundle"| node_truth_data
node_negative_builder -->|"reuses transformations"| node_truth_builder
node_truth_runner -.->|"evaluates against"| node_truth_data
node_negative_runner -.->|"evaluates against"| node_truth_data
node_explainer -.->|"writes records"| node_studies
node_truth_runner -.->|"writes records"| node_studies
node_negative_runner -.->|"writes records"| node_studies
node_optimal_stats -->|"reuses metrics"| node_explainer
node_optimal_stats -.->|"summarizes"| node_studies
node_seed_stats -->|"reuses metrics"| node_explainer
node_seed_stats -->|"uses statistics"| node_truth_stats
node_seed_stats -.->|"summarizes"| node_studies
node_truth_stats -.->|"summarizes"| node_studies

click node_cli "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/research_cli.py"
click node_config "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/configlib.py"
click node_contrastive "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/contrastive_runner.py"
click node_explainer "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/explanation_runner.py"
click node_gcj "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/patches/codegraph4ccdetector-overlay/reproduce_gcj.py"
click node_gcj_batch "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/patches/codegraph4ccdetector-overlay/reproduce_gcj_batched.py"
click node_truth_runner "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/truth_explanation_runner.py"
click node_negative_runner "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/negative_pair_truth_runner.py"
click node_truth_builder "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/build_transformation_explanation_truth.py"
click node_negative_builder "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/build_frozen_negative_pair_transformations.py"
click node_truth_data "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/external_data/explanation_truth/codenet_transformations/sources/g000_01710738b6__alpha.java"
click node_optimal_stats "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/aggregate_optimal_subgraph_study.py"
click node_seed_stats "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/aggregate_stochastic_explainer_seeds.py"
click node_truth_stats "https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/aggregate_explanation_truth_statistics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config toneBlue
class node_contrastive,node_explainer,node_gcj,node_gcj_batch toneAmber
class node_truth_runner,node_negative_runner,node_truth_builder,node_negative_builder,node_truth_data toneMint
class node_optimal_stats,node_seed_stats,node_truth_stats,node_studies toneRose
class node_researcher toneIndigo
```

## Components

### Experiment entry

- [Research CLI](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/research_cli.py): `research_cli.py`
- [Config resolver](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/configlib.py): `scripts/configlib.py`

### Explanation evaluation

- [Graph-pair runner](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/contrastive_runner.py): `scripts/contrastive_runner.py`
- [Pair explainers](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/explanation_runner.py): `scripts/explanation_runner.py`
- [GCJ reproduction](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/patches/codegraph4ccdetector-overlay/reproduce_gcj.py): `patches/codegraph4ccdetector-overlay/reproduce_gcj.py`
- [Batched GCJ runner](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/patches/codegraph4ccdetector-overlay/reproduce_gcj_batched.py): `patches/codegraph4ccdetector-overlay/reproduce_gcj_batched.py`

### Truth construction

- [Truth evaluator](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/truth_explanation_runner.py): `scripts/truth_explanation_runner.py`
- [Negative-pair evaluator](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/negative_pair_truth_runner.py): `scripts/negative_pair_truth_runner.py`
- [Transformation truth builder](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/build_transformation_explanation_truth.py): `scripts/build_transformation_explanation_truth.py`
- [Negative truth builder](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/build_frozen_negative_pair_transformations.py): `scripts/build_frozen_negative_pair_transformations.py`
- [Transformation bundles](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/external_data/explanation_truth/codenet_transformations/sources/g000_01710738b6__alpha.java): `external_data/explanation_truth/codenet_transformations/sources/g000_01710738b6__alpha.java`

### Study analysis

- [Optimal-study analysis](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/aggregate_optimal_subgraph_study.py): `scripts/aggregate_optimal_subgraph_study.py`
- [Seed analysis](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/aggregate_stochastic_explainer_seeds.py): `scripts/aggregate_stochastic_explainer_seeds.py`
- [Truth statistics](https://github.com/quanxiny/tc-sosp-code-clone-explanation/blob/main/scripts/aggregate_explanation_truth_statistics.py): `scripts/aggregate_explanation_truth_statistics.py`
- **Study records**

### Other components

- **Researcher**

## Connections

- Researcher → Research CLI: invokes (evidence: `README.md`)
- Research CLI → Config resolver: resolves (evidence: `research_cli.py`)
- Research CLI → Graph-pair runner: dispatches (evidence: `research_cli.py`)
- Research CLI → Pair explainers: dispatches (evidence: `research_cli.py`)
- Research CLI → Truth evaluator: dispatches (evidence: `research_cli.py`)
- Research CLI → Negative-pair evaluator: dispatches (evidence: `research_cli.py`)
- Graph-pair runner → Config resolver: uses (evidence: `scripts/contrastive_runner.py`)
- Graph-pair runner → GCJ reproduction: loads predictor (evidence: `scripts/contrastive_runner.py`)
- Graph-pair runner → Batched GCJ runner: loads predictor (evidence: `scripts/contrastive_runner.py`)
- Pair explainers → Config resolver: uses (evidence: `scripts/explanation_runner.py`)
- Pair explainers → Graph-pair runner: reuses graph model (evidence: `scripts/explanation_runner.py`)
- Pair explainers → GCJ reproduction: loads predictor (evidence: `scripts/explanation_runner.py`)
- Pair explainers → Batched GCJ runner: loads predictor (evidence: `scripts/explanation_runner.py`)
- Truth evaluator → Config resolver: uses (evidence: `scripts/truth_explanation_runner.py`)
- Truth evaluator → Graph-pair runner: reuses graph model (evidence: `scripts/truth_explanation_runner.py`)
- Truth evaluator → Pair explainers: calls explainers (evidence: `scripts/truth_explanation_runner.py`)
- Truth evaluator → Batched GCJ runner: loads predictor (evidence: `scripts/truth_explanation_runner.py`)
- Negative-pair evaluator → Config resolver: uses (evidence: `scripts/negative_pair_truth_runner.py`)
- Negative-pair evaluator → Graph-pair runner: reuses graph model (evidence: `scripts/negative_pair_truth_runner.py`)
- Negative-pair evaluator → Pair explainers: calls explainers (evidence: `scripts/negative_pair_truth_runner.py`)
- Negative-pair evaluator → Truth evaluator: reuses truth methods (evidence: `scripts/negative_pair_truth_runner.py`)
- Negative-pair evaluator → Batched GCJ runner: loads predictor (evidence: `scripts/negative_pair_truth_runner.py`)
- Transformation truth builder → Transformation bundles: creates bundle
- Negative truth builder → Transformation truth builder: reuses transformations (evidence: `scripts/build_frozen_negative_pair_transformations.py`)
- Truth evaluator → Transformation bundles: evaluates against
- Negative-pair evaluator → Transformation bundles: evaluates against
- Pair explainers → Study records: writes records
- Truth evaluator → Study records: writes records
- Negative-pair evaluator → Study records: writes records
- Optimal-study analysis → Pair explainers: reuses metrics (evidence: `scripts/aggregate_optimal_subgraph_study.py`)
- Optimal-study analysis → Study records: summarizes
- Seed analysis → Pair explainers: reuses metrics (evidence: `scripts/aggregate_stochastic_explainer_seeds.py`)
- Seed analysis → Truth statistics: uses statistics (evidence: `scripts/aggregate_stochastic_explainer_seeds.py`)
- Seed analysis → Study records: summarizes
- Truth statistics → Study records: summarizes (evidence: `README.md`)
