Merge branch 'feat/1.1.0'

Author: orenlab

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+-   repo: local
+    hooks:
+    -   id: codeclone
+        name: CodeClone
+        entry: codeclone
+        language: python
+        args: [".", "--fail-on-new"]
+        types: [python]

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [1.1.0] — 2026-01-19
+
+### Added
+
+- Control Flow Graph (CFG v1) for structural clone detection
+- Deterministic CFG-based function fingerprints
+- Interactive HTML report with syntax highlighting
+- Dark/light theme toggle in HTML report
+- Block-level clone visualization
+
+### Changed
+
+- Function clone detection now based on CFG instead of pure AST
+- Improved robustness against refactoring and control-flow changes
+
+### Documentation
+
+- Added `docs/cfg.md` with CFG semantics and limitations
+- Added `docs/architecture.md` describing system design
+
+---
+
+## [1.0.0] — 2026-01-17
+
+### Initial release
+
+- AST-based function clone detection
+- Block-level clone detection (Type-3-lite)
+- Baseline workflow for CI
+- JSON and text reports

README.md

@@ -5,69 +5,86 @@
 [![Python](https://img.shields.io/pypi/pyversions/codeclone.svg)](https://pypi.org/project/codeclone/)
 [![License](https://img.shields.io/pypi/l/codeclone.svg)](LICENSE)
 
-**CodeClone** is an AST-based Python code clone detector that helps teams find architectural duplication and prevent new
-copy-paste via CI.
+**CodeClone** is a Python code clone detector based on **normalized AST and control-flow graphs (CFG)**.
+It helps teams discover architectural duplication and prevent new copy-paste from entering the codebase via CI.
 
-It is designed to help teams:
+CodeClone is designed to help teams:
 
-- discover structural and logical code duplication,
-- understand architectural hotspots,
-- and prevent *new* duplication from entering the codebase via CI.
+- 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 works on **normalized Python AST**, which makes it robust against renaming,
+Unlike token- or text-based tools, CodeClone operates on **normalized Python AST and CFG**, making it robust against renaming,
 formatting, and minor refactoring.
 
 ---
 
 ## Why CodeClone?
 
 Most existing tools detect *textual* duplication.
-CodeClone detects **structural and block-level duplication** that usually indicates missing abstractions or
-architectural drift.
+CodeClone detects **structural and block-level duplication**, which usually signals missing abstractions or architectural drift.
 
 Typical use cases:
 
-- duplicated service logic across layers (API ↔ application),
+- duplicated service or orchestration logic across layers (API ↔ application),
 - repeated validation or guard blocks,
-- copy-pasted request/handler flows,
-- duplicated orchestration logic in routers, handlers, or services.
+- copy-pasted request / handler flows,
+- duplicated control-flow logic in routers, handlers, or services.
 
 ---
 
 ## Features
 
-### Function-level clone detection (Type-2)
+### Function-level clone detection (Type-2, CFG-based)
 
-- Detects functions and methods with identical structure.
+- Detects functions and methods with identical **control-flow structure**.
+- Based on **Control Flow Graph (CFG)** fingerprinting.
 - Robust to:
-    - variable renaming,
-    - constant changes,
-    - formatting differences.
-- Ideal for spotting architectural duplication between layers.
+  - variable renaming,
+  - constant changes,
+  - attribute renaming,
+  - formatting differences,
+  - docstrings and type annotations.
+- Ideal for spotting architectural duplication across layers.
 
 ### Block-level clone detection (Type-3-lite)
 
 - 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 avoid noise:
-    - no overlapping windows,
-    - no clones inside the same function,
-    - no `__init__` noise.
+  - 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.
+
+### Control-Flow Awareness (CFG v1)
+
+- Each function is converted into a **Control Flow Graph**.
+- CFG nodes contain normalized AST statements.
+- CFG edges represent structural control flow (`if`, `for`, `while`).
+- Current CFG semantics (v1):
+  - `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**.
 
 ### Low-noise by design
 
-- AST normalization instead of token matching.
-- Size and statement-count thresholds.
+- AST + CFG normalization instead of token matching.
 - Conservative defaults tuned for real-world Python projects.
+- Explicit thresholds for size and statement count.
+- Focus on *architectural duplication*, not micro-similarities.
 
 ### CI-friendly baseline mode
 
 - Establish a baseline of existing clones.
 - Fail CI **only when new clones are introduced**.
-- Safe for legacy codebases.
+- Safe for legacy codebases and incremental refactoring.
 
 ---
 
@@ -77,11 +94,11 @@ Typical use cases:
 pip install codeclone
 ```
 
-Python 3.10+ is required.
+Python **3.10+** is required.
 
-⸻
+---
 
-Quick Start
+## Quick Start
 
 Run on a project:
 
@@ -91,9 +108,10 @@ codeclone .
 
 This will:
 
-* scan Python files,
-* detect function-level and block-level clones,
-* print a summary to stdout.
+- scan Python files,
+- build CFGs for functions,
+- detect function-level and block-level clones,
+- print a summary to stdout.
 
 Generate reports:
 
@@ -103,81 +121,97 @@ codeclone . \
   --text-out .cache/codeclone/report.txt
 ```
 
-⸻
+Generate an HTML report:
+
+```bash
+codeclone . --html-out .cache/codeclone/report.html
+```
+
+---
 
-Baseline Workflow (Recommended)
+## Baseline Workflow (Recommended)
 
-1. Create a baseline
+### 1. Create a baseline
 
 Run once on your current codebase:
 
 ```bash
 codeclone . --update-baseline
 ```
 
-This creates a file:
+Commit the generated baseline file to the repository.
+
+### 2. Use in CI
 
 ```bash
-.codeclone-baseline.json
+codeclone . --fail-on-new
 ```
 
-Commit this file to the repository.
-
-⸻
+Behavior:
 
-2. Use in CI
+- ✅ existing clones are allowed,
+- ❌ build fails if *new* clones appear,
+- ✅ refactoring that removes duplication is always allowed.
 
-In CI, run:
+---
 
-```bash
-codeclone . --fail-on-new
+## Using with pre-commit
+
+```yaml
+repos:
+-   repo: local
+    hooks:
+    -   id: codeclone
+        name: CodeClone
+        entry: codeclone
+        language: python
+        args: [".", "--fail-on-new"]
+        types: [python]
 ```
 
-Behavior:
+---
 
-* ✅ existing clones are allowed,
-* ❌ build fails if new function or block clones appear,
-* ✅ refactoring that removes duplication is always allowed.
+## What CodeClone Is (and Is Not)
 
-This enables gradual improvement without breaking existing development flow.
+### CodeClone **is**
 
-⸻
+- an architectural analysis tool,
+- a duplication radar,
+- a CI guard against copy-paste,
+- a control-flow-aware clone detector.
 
-What CodeClone Is (and Is Not)
+### CodeClone **is not**
 
-CodeClone is
+- a linter,
+- a formatter,
+- a semantic equivalence prover,
+- a runtime analyzer.
 
-* an architectural analysis tool,
-* a duplication radar,
-* a CI guard against copy-paste.
+---
+
+## How It Works (High Level)
 
-CodeClone is not
+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. Detect function-level and block-level clones.
+6. Apply conservative filters to suppress noise.
 
-* a linter,
-* a formatter,
-* a replacement for SonarQube or static analyzers,
-* a semantic equivalence prover.
+---
 
-It intentionally focuses on high-signal duplication.
+## Control Flow Graph (CFG)
 
-⸻
+Starting from **version 1.1.0**, CodeClone uses a **Control Flow Graph (CFG)**
+to improve structural clone detection robustness.
 
-How It Works (High Level)
+The CFG is a **structural abstraction**, not a runtime execution model.
 
-* Parses Python source into AST.
-* Normalizes:
-    - variable names,
-    - constants,
-    - attributes,
-    - docstrings and annotations.
-* Computes stable structural fingerprints.
-* Detects:
-    - identical function structures,
-    - repeated statement blocks across functions.
-* Applies filters to suppress noise.
+See full design and semantics:
+- [docs/cfg.md](docs/cfg.md)
 
-⸻
+---
 
-License
+## License
 
-MIT License
+MIT License

codeclone/__init__.py

@@ -0,0 +1,16 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("codeclone")
+except PackageNotFoundError:
+    __version__ = "dev"
+
+__all__ = ["__version__"]

codeclone/baseline.py

@@ -1,3 +1,11 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
 from __future__ import annotations
 
 import json

codeclone/blockhash.py

@@ -1,12 +1,21 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
 from __future__ import annotations
 
 import ast
 import hashlib
 
 from .normalize import NormalizationConfig, AstNormalizer
 
+
 def stmt_hash(stmt: ast.stmt, cfg: NormalizationConfig) -> str:
     normalizer = AstNormalizer(cfg)
     stmt = ast.fix_missing_locations(normalizer.visit(stmt))
     dump = ast.dump(stmt, annotate_fields=True, include_attributes=False)
-    return hashlib.sha1(dump.encode("utf-8")).hexdigest()
+    return hashlib.sha1(dump.encode("utf-8")).hexdigest()