Data Models
Relevant source files
The following files were used as context for generating this wiki page:
The Duplicate Code Detection Tool utilizes a structured set of data models to represent the results of similarity analysis between source code files. These models facilitate the transition from raw similarity scores generated by the analysis engine to meaningful, actionable reports used by developers and CI/CD pipelines.
The data models are primarily defined in core.py as Python dataclasses, providing a clean API for library consumers, while internal logic in duplicate_code_detection.py handles the low-level data structures and execution states.
Core Data Structures
The system organizes detection data into a hierarchy starting from individual file comparisons up to a comprehensive result object for an entire project analysis.
Class Hierarchy and Relationships
The following diagram illustrates the relationship between the primary data models in the system.
The hierarchy ensures that every analysis run produces a DetectionResult, which encapsulates various SimilarityReport objects for each file, which in turn contain specific FileSimilarity details.
Sources: core.py:25-115, duplicate_code_detection.py:33-36
Data Model Definitions
| Model | Description | Source |
|---|---|---|
FileSimilarity | Represents a pair-wise similarity between two specific files, including their similarity percentage and line counts (LoC). | core.py:25-39 |
SimilarityReport | Aggregates all similarity findings for a single source file, allowing for filtering based on thresholds. | core.py:42-62 |
DetectionResult | The top-level container for a full analysis run. It includes the execution status and helper methods to query findings. | core.py:65-103 |
ReturnCode | An Enumeration defining the possible exit states of the detection tool. | duplicate_code_detection.py:33-36 |
Similarity Representation
The FileSimilarity dataclass is the most granular model, capturing the relationship between a source_file and a target_file.
@dataclass
class FileSimilarity:
source_file: str
target_file: str
similarity_percentage: float
source_loc: int | None = None
target_loc: int | None = None
Sources: core.py:25-32
This model supports JSON serialization via a to_dict() method, which is used when generating machine-readable reports for CI/CD integrations or API responses.
Sources: core.py:34-41, run_action.py:126-140
Execution Status and Results
The DetectionResult class manages the lifecycle of an analysis run. It holds a ReturnCode and provides logic to determine if the run was successful or if duplications exceeded specific thresholds.
ReturnCode Enum
The tool defines three distinct states for any given run:
- SUCCESS (0): The tool ran correctly and no critical thresholds were exceeded.
- BAD_INPUT (1): The provided directories or files were invalid (e.g., path does not exist).
- THRESHOLD_EXCEEDED (2): Similarity was found above the user-defined
fail_threshold.
Sources: duplicate_code_detection.py:33-36, core.py:73-75
Critical Duplication Logic
The DetectionResult model provides a get_critical_duplications() method that flattens the hierarchy to return a list of all FileSimilarity objects across all reports that exceed a specific percentage.
Sources: core.py:81-90
Configuration Data
While not defined as a specific class, the tool's input parameters are modeled as a set of configuration options passed to the DuplicateCodeDetector. These options influence how the data models are populated.
| Parameter | Type | Default | Description | Source |
|---|---|---|---|---|
fail_threshold | int | 100 | Similarity percentage at which ReturnCode becomes THRESHOLD_EXCEEDED. | duplicate_code_detection.py:116-121 |
ignore_threshold | int | 15 (core) / 0 (cli) | Similarities below this percentage are excluded from reports. | core.py:112, duplicate_code_detection.py:155-159 |
only_code | bool | False | If True, removes comments/docstrings before populating similarity data. | duplicate_code_detection.py:160-163 |
show_loc | bool | True | If True, includes line count data in the models. | core.py:115 |
Sources: core.py:106-125, action.yml:4-46
Summary of Data Flow
The data flow converts raw file content into the structured models described above.
The DuplicateCodeDetector._process_result method acts as the primary factory for transforming the raw dictionary output from the core logic into the typed DetectionResult and SimilarityReport objects.
Sources: core.py:173-214, duplicate_code_detection.py:202-315