CodeClone is a Python code clone detector based on normalized Python AST and Control Flow Graphs (CFG). It helps teams discover architectural duplication and prevent new copy-paste from entering the codebase via CI.

CodeClone is designed to help teams:

• discover structural and control-flow duplication,
• identify architectural hotspots,
• prevent new duplication via CI and pre-commit hooks.

Unlike token- or text-based tools, CodeClone operates on normalized Python AST and CFG, making it robust against renaming, formatting, and minor refactoring.

Most existing tools detect textual duplication. CodeClone detects structural and block-level duplication, which usually signals missing abstractions or architectural drift.

Typical use cases:

• duplicated service or orchestration logic across layers (API ↔ application),
• repeated validation or guard blocks,
• copy-pasted request / handler flows,
• duplicated control-flow logic in routers, handlers, or services.

• Detects functions and methods with identical control-flow structure.
• Based on Control Flow Graph (CFG) fingerprinting.
• Robust to:
  • variable renaming,
  • constant changes,
  • attribute renaming,
  • formatting differences,
  • docstrings and type annotations.
• Ideal for spotting architectural duplication across layers.

• Detects repeated statement blocks inside larger functions.
• Uses sliding windows over CFG-normalized statement sequences.
• Targets:
  • validation blocks,
  • guard clauses,
  • repeated orchestration logic.
• Carefully filtered to reduce noise:
  • no overlapping windows,
  • no clones inside the same function,
  • no __init__ noise,
  • size and statement-count thresholds.

• Detects repeated segment windows inside the same function.
• Uses a two‑step deterministic match (candidate signature → strict hash).
• Included in reports for explainability, not in baseline/CI failure logic.

• Each function is converted into a Control Flow Graph.
• CFG nodes contain normalized AST statements.
• CFG edges represent structural control flow:
  • if / else
  • for / async for / while
  • try / except / finally
  • with / async with
  • match / case (Python 3.10+)
• Current CFG semantics (v1):
  • and / or are modeled as short‑circuit micro‑CFG branches,
  • try/except links only from statements that may raise,
  • break and continue are treated as statements (no jump targets),
  • after-blocks are explicit and always present,
  • focus is on structural similarity, not precise runtime semantics.

This design keeps clone detection stable, deterministic, and low-noise.

• AST + CFG normalization instead of token matching.
• Conservative defaults tuned for real-world Python projects.
• Explicit thresholds for size and statement count.
• No probabilistic scoring or heuristic similarity thresholds.
• Safe commutative normalization and local logical equivalences only.
• Focus on architectural duplication, not micro-similarities.

• Establish a baseline of existing clones.
• Fail CI only when new clones are introduced.
• Safe for legacy codebases and incremental refactoring.

pip install codeclone

Python 3.10+ is required.

Run on a project:

codeclone .

This will:

• scan Python files,
• build CFGs for functions,
• detect function-level and block-level clones,
• print a summary to stdout.

Generate reports:

codeclone . \
  --json .cache/codeclone/report.json \
  --text .cache/codeclone/report.txt

All report formats include provenance metadata for auditability: codeclone_version, python_version, baseline_path, baseline_version, baseline_schema_version, baseline_python_version, baseline_loaded, baseline_status (and cache metadata when available).

Generate an HTML report:

codeclone . --html .cache/codeclone/report.html

Check version:

codeclone --version

Run once on your current codebase:

codeclone . --update-baseline

Commit the generated baseline file to the repository.

Baselines are versioned. If CodeClone is upgraded, regenerate the baseline to keep CI deterministic and explainable.

codeclone . --ci

or:

codeclone . --ci --html .cache/codeclone/report.html

--ci is equivalent to --fail-on-new --no-color --quiet.

Behavior:

• existing clones are allowed,
• the build fails if new clones appear,
• refactoring that removes duplication is always allowed.

--fail-on-new exits with a non-zero code when new clones are detected.

By default, CodeClone stores the cache per project at:

<root>/.cache/codeclone/cache.json

You can override this path with --cache-path (--cache-dir is a legacy alias).

If you used an older version of CodeClone, delete the legacy cache file at ~/.cache/codeclone/cache.json and add .cache/ to .gitignore.

Due to inherent differences in Python’s AST between interpreter versions, baseline generation and verification must be performed using the same Python version.

This ensures deterministic and reproducible clone detection results.

CI checks therefore pin baseline verification to a single Python version, while the test matrix continues to validate compatibility across Python 3.10–3.14.

repos:
  - repo: local
    hooks:
      - id: codeclone
        name: CodeClone
        entry: codeclone
        language: system
        pass_filenames: false
        args: [ ".", "--ci" ]
        types: [ python ]

• an architectural analysis tool,
• a duplication radar,
• a CI guard against copy-paste,
• a control-flow-aware clone detector.

• a linter,
• a formatter,
• a semantic equivalence prover,
• a runtime analyzer.

1. Parse Python source into AST.
2. Normalize AST (names, constants, attributes, annotations).
3. Build a Control Flow Graph (CFG) per function.
4. Compute stable CFG fingerprints.
5. Extract segment windows for internal clone discovery.
6. Detect function-level, block-level, and segment-level clones.
7. Apply conservative filters to suppress noise.

See the architectural overview:

• docs/architecture.md

Starting from version 1.1.0, CodeClone uses a Control Flow Graph (CFG) to improve structural clone detection robustness.

The CFG is a structural abstraction, not a runtime execution model.

See full design and semantics:

• docs/cfg.md

MIT License