Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pyproject.toml
• setup.py
• duplicate_code_detection.py
• core.py
• run_action.py

This guide outlines the standards and procedures for contributing to the Duplicate Code Detection Tool. The project is a Python-based library and CLI tool designed to identify code similarities across files and directories, supporting modern Python standards (3.8 to 3.13) and integration into CI/CD pipelines.

Contributors are expected to follow established coding styles, maintain technical accuracy in similarity logic, and ensure that all new features or bug fixes are accompanied by appropriate tests and documentation updates.

Sources: README.md:1-15, pyproject.toml:23-35

Development Workflow

The project follows a standard GitHub-based contribution workflow. Contributors should fork the repository, create feature-specific branches, and submit pull requests for review.

The workflow ensures that all code is validated against the existing test suite and linting rules before merging.
Sources: README.md:275-285

Environment Setup

To set up a development environment, install the project in editable mode with development dependencies:

pip install -e ".[dev]"

Sources: README.md:255-257

Technical Standards

Coding Style and Quality

The project enforces strict code quality standards using black, isort, flake8, and mypy. These tools are configured to maintain a line length of 88 characters and ensure type safety across the codebase.

Tool	Purpose	Configuration File
black	Code Formatting	pyproject.toml
isort	Import Sorting	pyproject.toml
mypy	Static Type Checking	pyproject.toml
pytest	Unit Testing	pyproject.toml

Sources: pyproject.toml:77-128

Type Hinting

All new contributions must include type hints. The mypy configuration is set to strict_equality and requires untyped definitions to be flagged.
Sources: pyproject.toml:98-112

Core Architecture and Logic

Contributors modifying the detection engine should understand the interaction between the high-level core.py classes and the underlying duplicate_code_detection.py implementation.

Similarity Detection Flow

The detection process involves tokenization, TF-IDF modeling, and similarity matrix generation via gensim.

The logic differentiates between pure code analysis and full-file analysis based on the only_code flag.
Sources: duplicate_code_detection.py:190-230, core.py:155-180

Key Components

• DuplicateCodeDetector: The primary entry point for library usage. It wraps the run function and processes raw dictionary data into structured DetectionResult objects.
• SimilarityReport: Aggregates all FileSimilarity instances for a specific source file.
• run(): The core functional engine that handles file I/O, directory walking, and the gensim similarity pipeline.

Sources: core.py:126-150, duplicate_code_detection.py:146-170

Testing Requirements

Before submitting a Pull Request, contributors must ensure the test suite passes and coverage is maintained. The project uses pytest for all testing activities.

# Run tests
pytest

# Run with coverage report
pytest --cov=duplicate_code_tool

Sources: README.md:260-264

Coverage Standards

Code coverage is tracked for the duplicate_code_tool source. Specific paths like tests/ and __pycache__ are omitted from the report.
Sources: pyproject.toml:139-155

Documentation and Metadata

Changes to the project structure or dependencies must be reflected in the following files:

• pyproject.toml: Contains build-system requirements, project metadata, and tool configurations.
• README.md: Must be updated for any changes to the CLI arguments or Library API.
• action.yml: Must be updated if there are changes to the GitHub Action inputs or environment variables.

GitHub Action Integration

The tool functions as a GitHub Action, utilizing run_action.py to format results into Markdown tables and post them as PR comments. If modifying the reporting format, ensure the make_markdown_table function in run_action.py is updated.

Sources: run_action.py:14-55, action.yml:4-45

Summary

Contributors are the backbone of the Duplicate Code Detection Tool. By adhering to the black formatting standard, providing full type hints, and ensuring the gensim-based similarity engine remains accurate, you help maintain a robust tool for the Flext community and beyond. Always verify that pytest passes locally before initiating a Pull Request.

Sources: README.md:295-300, pyproject.toml:5-15