codeclone 1.4.4__tar.gz → 2.0.0b2__tar.gz

{codeclone-1.4.4 → codeclone-2.0.0b2}/LICENSE

@@ -2,6 +2,8 @@ MIT License
 
 Copyright (c) 2024 Denis Rozhnovskiy
 
+The name “CodeClone” refers to the official project distribution.
+
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

codeclone-2.0.0b2/PKG-INFO

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: codeclone
+Version: 2.0.0b2
+Summary: Structural code quality analysis for Python
+Author-email: Den Rozhnovskiy <pytelemonbot@mail.ru>
+Maintainer-email: Den Rozhnovskiy <pytelemonbot@mail.ru>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/orenlab/codeclone
+Project-URL: Repository, https://github.com/orenlab/codeclone
+Project-URL: Issues, https://github.com/orenlab/codeclone/issues
+Project-URL: Changelog, https://github.com/orenlab/codeclone/releases
+Project-URL: Documentation, https://orenlab.github.io/codeclone/
+Keywords: python,ast,cfg,code-clone,duplication,static-analysis,architecture,control-flow,ci
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygments>=2.19.2
+Requires-Dist: rich>=14.3.2
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: build>=1.4.1; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.19.1; extra == "dev"
+Requires-Dist: ruff>=0.15.8; extra == "dev"
+Requires-Dist: pre-commit>=4.5.1; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://orenlab.github.io/codeclone/assets/codeclone-wordmark.svg" alt="CodeClone" height="60">
+</p>
+
+<p align="center">
+  <strong>Structural code quality analysis for Python</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/codeclone/"><img src="https://img.shields.io/pypi/v/codeclone.svg?style=flat-square" alt="PyPI"></a>
+  <a href="https://pypi.org/project/codeclone/"><img src="https://img.shields.io/pypi/dm/codeclone.svg?style=flat-square" alt="Downloads"></a>
+  <a href="https://github.com/orenlab/codeclone/actions/workflows/tests.yml"><img src="https://github.com/orenlab/codeclone/actions/workflows/tests.yml/badge.svg?branch=main&style=flat-square" alt="Tests"></a>
+  <a href="https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml"><img src="https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml/badge.svg?style=flat-square" alt="Benchmark"></a>
+  <a href="https://pypi.org/project/codeclone/"><img src="https://img.shields.io/pypi/pyversions/codeclone.svg?style=flat-square" alt="Python"></a>
+  <a href="https://github.com/orenlab/codeclone"><img src="https://img.shields.io/badge/codeclone-81%20(B)-green" alt="codeclone 81 (B)"></a>
+  <a href="https://github.com/orenlab/codeclone/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/codeclone.svg?style=flat-square" alt="License"></a>
+</p>
+
+---
+
+CodeClone provides comprehensive structural code quality analysis for Python. It detects architectural
+duplication via normalized AST and Control Flow Graphs, computes quality metrics, and enforces CI gates —
+all with baseline-aware governance that separates **known** technical debt from **new** regressions.
+
+Docs: [orenlab.github.io/codeclone](https://orenlab.github.io/codeclone/) ·
+Live sample report:
+[orenlab.github.io/codeclone/examples/report/](https://orenlab.github.io/codeclone/examples/report/)
+
+## Features
+
+- **Clone detection** — function (CFG fingerprint), block (statement windows), and segment (report-only) clones
+- **Structural findings** — duplicated branch families, clone guard/exit divergence and clone-cohort drift (report-only)
+- **Quality metrics** — cyclomatic complexity, coupling (CBO), cohesion (LCOM4), dependency cycles, dead code, health
+  score
+- **Baseline governance** — known debt stays accepted; CI blocks only new clones and metric regressions
+- **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report
+- **CI-first** — deterministic output, stable ordering, exit code contract, pre-commit support
+- **Fast*** — incremental caching, parallel processing, warm-run optimization, and reproducible benchmark coverage
+
+## Quick Start
+
+```bash
+pip install codeclone        # or: uv tool install codeclone
+
+codeclone .                  # analyze current directory
+codeclone . --html           # generate HTML report
+codeclone . --html --open-html-report   # generate and open HTML report
+codeclone . --json --md --sarif --text   # generate machine-readable reports
+codeclone . --html --json --timestamped-report-paths   # keep timestamped report snapshots
+codeclone . --ci             # CI mode (--fail-on-new --no-color --quiet)
+```
+
+<details>
+<summary>Run without install</summary>
+
+```bash
+uvx codeclone@latest .
+```
+
+</details>
+
+## CI Integration
+
+```bash
+# 1. Generate baseline (commit to repo)
+codeclone . --update-baseline
+
+# 2. Add to CI pipeline
+codeclone . --ci
+```
+
+The `--ci` preset equals `--fail-on-new --no-color --quiet`.
+When a trusted metrics baseline is loaded, CI mode also enables
+`--fail-on-new-metrics`.
+
+### Quality Gates
+
+```bash
+# Metrics thresholds
+codeclone . --fail-complexity 20 --fail-coupling 10 --fail-cohesion 4 --fail-health 60
+
+# Structural policies
+codeclone . --fail-cycles --fail-dead-code
+
+# Regression detection vs baseline
+codeclone . --fail-on-new-metrics
+```
+
+### Pre-commit
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: codeclone
+        name: CodeClone
+        entry: codeclone
+        language: system
+        pass_filenames: false
+        args: [ ".", "--ci" ]
+        types: [ python ]
+```
+
+## Configuration
+
+CodeClone can load project-level configuration from `pyproject.toml`:
+
+```toml
+[tool.codeclone]
+min_loc = 10
+min_stmt = 6
+baseline = "codeclone.baseline.json"
+skip_metrics = false
+quiet = false
+html_out = ".cache/codeclone/report.html"
+json_out = ".cache/codeclone/report.json"
+md_out = ".cache/codeclone/report.md"
+sarif_out = ".cache/codeclone/report.sarif"
+text_out = ".cache/codeclone/report.txt"
+block_min_loc = 20
+block_min_stmt = 8
+segment_min_loc = 20
+segment_min_stmt = 10
+```
+
+Precedence: CLI flags > `pyproject.toml` > built-in defaults.
+
+## Baseline Workflow
+
+Baselines capture the current duplication state. Once committed, they become the CI reference point.
+
+- Clones are classified as **NEW** (not in baseline) or **KNOWN** (accepted debt)
+- `--update-baseline` writes both clone and metrics snapshots
+- Trust is verified via `generator`, `fingerprint_version`, and `payload_sha256`
+- In `--ci` mode, an untrusted baseline is a contract error (exit 2)
+
+Full contract: [Baseline contract](https://orenlab.github.io/codeclone/book/06-baseline/)
+
+## Exit Codes
+
+| Code | Meaning                                                                       |
+|------|-------------------------------------------------------------------------------|
+| `0`  | Success                                                                       |
+| `2`  | Contract error — untrusted baseline, invalid config, unreadable sources in CI |
+| `3`  | Gating failure — new clones or metric threshold exceeded                      |
+| `5`  | Internal error                                                                |
+
+Contract errors (`2`) take precedence over gating failures (`3`).
+
+## Reports
+
+| Format   | Flag      | Default path                    |
+|----------|-----------|---------------------------------|
+| HTML     | `--html`  | `.cache/codeclone/report.html`  |
+| JSON     | `--json`  | `.cache/codeclone/report.json`  |
+| Markdown | `--md`    | `.cache/codeclone/report.md`    |
+| SARIF    | `--sarif` | `.cache/codeclone/report.sarif` |
+| Text     | `--text`  | `.cache/codeclone/report.txt`   |
+
+All report formats are rendered from one canonical JSON report document.
+
+- `--open-html-report` opens the generated HTML report in the default browser and requires `--html`.
+- `--timestamped-report-paths` appends a UTC timestamp to default report filenames for bare report flags such as
+  `--html` or `--json`. Explicit report paths are not rewritten.
+
+The published docs site also includes a live example HTML/JSON/SARIF report
+generated from the current `codeclone` repository during the docs build.
+
+Structural findings include:
+
+- `duplicated_branches`
+- `clone_guard_exit_divergence`
+- `clone_cohort_drift`
+
+### Inline Suppressions
+
+CodeClone keeps dead-code detection deterministic and static by default. When a symbol is intentionally
+invoked through runtime dynamics (for example framework callbacks, plugin loading, or reflection), suppress
+the known false positive explicitly at the declaration site:
+
+```python
+# codeclone: ignore[dead-code]
+def handle_exception(exc: Exception) -> None:
+    ...
+
+
+class Middleware:  # codeclone: ignore[dead-code]
+    ...
+```
+
+Dynamic/runtime false positives are resolved via explicit inline suppressions, not via broad heuristics.
+
+<details>
+<summary>JSON report shape (v2.1)</summary>
+
+```json
+{
+  "report_schema_version": "2.1",
+  "meta": {
+    "codeclone_version": "2.0.0b2",
+    "project_name": "...",
+    "scan_root": ".",
+    "report_mode": "full",
+    "baseline": {
+      "...": "..."
+    },
+    "cache": {
+      "...": "..."
+    },
+    "metrics_baseline": {
+      "...": "..."
+    },
+    "runtime": {
+      "report_generated_at_utc": "..."
+    }
+  },
+  "inventory": {
+    "files": {
+      "...": "..."
+    },
+    "code": {
+      "...": "..."
+    },
+    "file_registry": {
+      "encoding": "relative_path",
+      "items": []
+    }
+  },
+  "findings": {
+    "summary": {
+      "...": "..."
+    },
+    "groups": {
+      "clones": {
+        "functions": [],
+        "blocks": [],
+        "segments": []
+      },
+      "structural": {
+        "groups": []
+      },
+      "dead_code": {
+        "groups": []
+      },
+      "design": {
+        "groups": []
+      }
+    }
+  },
+  "metrics": {
+    "summary": {},
+    "families": {}
+  },
+  "derived": {
+    "suggestions": [],
+    "overview": {
+      "families": {},
+      "top_risks": [],
+      "source_scope_breakdown": {},
+      "health_snapshot": {}
+    },
+    "hotlists": {
+      "most_actionable_ids": [],
+      "highest_spread_ids": [],
+      "production_hotspot_ids": [],
+      "test_fixture_hotspot_ids": []
+    }
+  },
+  "integrity": {
+    "canonicalization": {
+      "version": "1",
+      "scope": "canonical_only"
+    },
+    "digest": {
+      "algorithm": "sha256",
+      "verified": true,
+      "value": "..."
+    }
+  }
+}
+```
+
+Canonical contract: [Report contract](https://orenlab.github.io/codeclone/book/08-report/) and
+[Dead-code contract](https://orenlab.github.io/codeclone/book/16-dead-code-contract/)
+
+</details>
+
+## How It Works
+
+1. **Parse** — Python source to AST
+2. **Normalize** — canonical structure (robust to renaming, formatting)
+3. **CFG** — per-function control flow graph
+4. **Fingerprint** — stable hash computation
+5. **Group** — function, block, and segment clone groups
+6. **Metrics** — complexity, coupling, cohesion, dependencies, dead code, health
+7. **Gate** — baseline comparison, threshold checks
+
+Architecture: [Architecture narrative](https://orenlab.github.io/codeclone/architecture/) ·
+CFG semantics: [CFG semantics](https://orenlab.github.io/codeclone/cfg/)
+
+## Documentation
+
+| Topic                      | Link                                                                                               |
+|----------------------------|----------------------------------------------------------------------------------------------------|
+| Contract book (start here) | [Contracts and guarantees](https://orenlab.github.io/codeclone/book/00-intro/)                    |
+| Exit codes                 | [Exit codes and failure policy](https://orenlab.github.io/codeclone/book/03-contracts-exit-codes/) |
+| Configuration              | [Config and defaults](https://orenlab.github.io/codeclone/book/04-config-and-defaults/)           |
+| Baseline contract          | [Baseline contract](https://orenlab.github.io/codeclone/book/06-baseline/)                        |
+| Cache contract             | [Cache contract](https://orenlab.github.io/codeclone/book/07-cache/)                              |
+| Report contract            | [Report contract](https://orenlab.github.io/codeclone/book/08-report/)                            |
+| Metrics & quality gates    | [Metrics and quality gates](https://orenlab.github.io/codeclone/book/15-metrics-and-quality-gates/) |
+| Dead code                  | [Dead-code contract](https://orenlab.github.io/codeclone/book/16-dead-code-contract/)             |
+| Docker benchmark contract  | [Benchmarking contract](https://orenlab.github.io/codeclone/book/18-benchmarking/)                |
+| Determinism                | [Determinism policy](https://orenlab.github.io/codeclone/book/12-determinism/)                    |
+
+## * Benchmarking
+
+<details>
+<summary>Reproducible Docker Benchmark</summary>
+
+```bash
+./benchmarks/run_docker_benchmark.sh
+```
+
+The wrapper builds `benchmarks/Dockerfile`, runs isolated container benchmarks, and writes results to
+`.cache/benchmarks/codeclone-benchmark.json`.
+
+Use environment overrides to pin the benchmark envelope:
+
+```bash
+CPUSET=0 CPUS=1.0 MEMORY=2g RUNS=16 WARMUPS=4 \
+  ./benchmarks/run_docker_benchmark.sh
+```
+
+Performance claims are backed by the reproducible benchmark workflow documented
+in [Benchmarking contract](https://orenlab.github.io/codeclone/book/18-benchmarking/)
+
+</details>
+
+## Links
+
+- **Issues:** <https://github.com/orenlab/codeclone/issues>
+- **PyPI:** <https://pypi.org/project/codeclone/>
+- **License:** MIT