codeecho 1.1.0

A developer tool that scans your codebase to detect and highlight echoes of duplicated or near-duplicated code, so you can refactor toward cleaner, more maintainable designs.

Prerequisites

• Python >=3.14

Installation

pip install codeecho

Usage

python -m codeecho <path> [options]

Clone detection levels

Type	Detection strategy	Example
Type-1	Exact copy-paste — identical token sequences	Two functions with the same code copied verbatim
Type-2	Structural clone — same structure, renamed identifiers / literals	Same logic with different variable names
Type-3	Near-duplicate — high Jaccard similarity on token sets	Nearly identical functions with a few extra lines

Supported languages

Language	Extensions	Grammar
Python	.py	tree-sitter-python
JavaScript	.js, .mjs, .cjs	tree-sitter-javascript
TypeScript	.ts, .tsx	tree-sitter-typescript
Java	.java	tree-sitter-java
Go	.go	tree-sitter-go
Gosu	.gs, .gsx	tree-sitter-gosu

Arguments

Argument	Description
path	Root directory to scan.

Options

Option	Default	Description
--types <types>	all	Clone types to detect: comma-separated (1, 2, 3) or all.
--threshold <float>	0.8	Jaccard similarity threshold for Type-3 detection (0.0–1.0).
--output <name>	codeecho-output	Base name (without extension) for output file(s).
--output-dir <dir>	<cwd>/reports	Directory where output file(s) will be written.
--db-dir <dir>	~/.codeecho	Directory for the SQLite scratch database (codeecho.db). Session records are removed after the report is written.
--format <fmt>	both	Output format: json, html, or both.
--min-tokens <n>	10	Minimum token count for a code fragment to be included.
--exclude <pattern>	(none)	Glob pattern(s) to exclude from scanning (repeatable).
--version		Print the version and exit.
-h, --help		Show help and exit.

Examples

Scan the current directory and write both JSON and HTML reports:

python -m codeecho .

Detect only Type-1 and Type-2 clones in a src/ tree:

python -m codeecho src --types 1,2

Scan with a custom output name and directory:

python -m codeecho . --output my-scan --output-dir audit/reports

Lower the Type-3 threshold to catch more near-duplicates:

python -m codeecho . --threshold 0.6

Exclude test and vendor directories:

python -m codeecho . --exclude "*/tests/*" --exclude "*/vendor/*"

Configuration

Environment variable	Description
CODEECHO_CONFIG_DIR	Directory where logging.ini and .ignore are seeded on first run. When unset, the bundled copies inside the package are used directly.

.ignore file

On first run, a .ignore file is seeded into CODEECHO_CONFIG_DIR (or the package directory when unset). It follows gitignore syntax and is applied during file scanning to exclude paths in addition to any --exclude patterns passed on the command line. Edit this file to permanently suppress paths you never want scanned.

Development

Prerequisites

• Poetry 2.2+

Setup

poetry install

Run

poetry run python -m codeecho <path> [options]

Architecture

flowchart TD
    CLI["__main__.py\n(Click CLI)"] --> ScannerM["scanner.py\nFile discovery"]
    ScannerM --> Parser["parser.py\nTree-sitter parsing"]
    Parser --> Extractor["extractor.py\nFragment extraction\n(functions · classes · files)"]
    Extractor --> Normalizer["normalizer.py\nRegex tokeniser\nType-2 normalisation"]
    Normalizer --> Fingerprint["fingerprint.py\nSHA-256 hashing"]
    Fingerprint --> DB["db.py\nSQLite session store"]
    DB --> Detector["detector.py\nType-1 / 2 hash grouping\nType-3 Jaccard similarity"]
    Detector --> DB
    DB --> JSON["reporter/json_reporter.py\nJSON report"]
    DB --> HTML["reporter/html_reporter.py\nHTML report"]
    DB -->|delete session| Cleanup["Session cleanup"]

Format and Lint

poetry run black codeecho
poetry run pylint codeecho

Run Tests with Coverage

poetry run pytest --cov=codeecho tests --cov-report html

Changelog

License

This project is licensed under the MIT License.

Author

Ron Webb