JSON Export

The JSON Export feature in the Duplicate Code Detection Tool provides a machine-readable representation of code similarity analysis results. It is designed to facilitate integration with CI/CD pipelines, automated code quality gates, and third-party reporting tools by providing a structured format for programmatically processing detected duplications.

Sources: README.md:12-19, core.py:7-12

Architecture and Data Flow

The JSON generation process occurs at two levels: the core execution engine and the high-level library wrapper. The run function in the core module calculates similarities and produces a raw dictionary that can be serialized to JSON. The DetectionResult class in the library wrapper provides a more structured to_json() method for end-user applications.

The system uses standard Python json serialization to convert internal data structures into strings. In the core logic, if the json_output flag is set, the tool prints the serialized similarity dictionary directly to standard output.

Sources: duplicate_code_detection.py:317-319, core.py:102-104

Data Structures and Schema

The JSON output follows a nested structure where the top-level keys are the source file paths. Depending on the configuration (specifically the show_loc flag), the internal structure of these entries varies.

Standard Output Structure

When show_loc is disabled, the JSON maps source files to a dictionary of target files and their similarity percentages.

{
  "file1.py": {
    "file2.py": 85.5,
    "file3.py": 20.1
  }
}

Sources: duplicate_code_detection.py:317-319, run_action.py:127-142

Detailed Output Structure (with LOC)

When show_loc is enabled, the structure expands to include Line of Code (LoC) metadata for both the source file and its targets.

Sources: duplicate_code_detection.py:270-295, core.py:30-40

Implementation Details

Library Export Logic

The DetectionResult class provides the primary interface for JSON export in library integrations. It utilizes a to_dict() method to recursively transform internal dataclasses (SimilarityReport, FileSimilarity) into a serializable format.

The to_json() method supports custom indentation, defaulting to a value of 2 for readability.

Sources: core.py:76-114

CLI and Action Integration

The Command Line Interface (CLI) triggers JSON export via the -j or --json flag. In the context of GitHub Actions, the run_action.py script utilizes the json_output=True parameter when calling the core engine to ensure results are available for reporting.

detection_result, code_similarity = duplicate_code_detection.run(
    int(fail_threshold),
    directories_list,
    None,
    ignore_directories_list,
    None,
    True, # json_output flag
    project_root_dir,
    file_extensions_list,
    int(ignore_threshold),
    bool(only_code),
    "",
    False
)

Sources: run_action.py:127-142, duplicate_code_detection.py:182-184

Usage Examples

Generating a Report File

In Flext CI/CD integrations, the JSON output is often captured and saved to a file for persistent logging or subsequent analysis steps.

# Generate detailed report for CI/CD
report_path = "duplication_report.json"
with open(report_path, "w") as f:
    f.write(result.to_json())

Sources: examples/flext_integration_example.py:130-134

CI/CD Quality Gates

The structured nature of the JSON allows for automated success/failure logic based on duplication thresholds. The DetectionResult object encapsulates the JSON data and provides helper methods like is_success() which correlates with the ReturnCode found in the JSON payload.

Sources: core.py:86-95, examples/flext_integration_example.py:118-125

Summary

The JSON Export feature provides the necessary structural foundation for automating code quality workflows. By offering both raw similarity data and a refined, object-oriented representation via the library wrapper, it supports a wide range of use cases from simple CLI redirects to complex CI/CD pipeline integrations.

Sources: README.md:204-215, core.py:102-114