{"id":39159920,"url":"https://github.com/orenlab/codeclone","last_synced_at":"2026-04-05T20:02:16.809Z","repository":{"id":332822616,"uuid":"1135125713","full_name":"orenlab/codeclone","owner":"orenlab","description":"Deterministic structural code quality analysis for Python with baseline-aware governance, canonical reporting, and an optional MCP interface for agents and IDEs.","archived":false,"fork":false,"pushed_at":"2026-04-02T15:54:30.000Z","size":2636,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T01:42:57.648Z","etag":null,"topics":["agentic-development","ast","baseline","ci","clone-detection","code-quality","dead-code","deterministic-reporting","mcp","python","quality-gates","software-metrics","static-analysis"],"latest_commit_sha":null,"homepage":"https://orenlab.github.io/codeclone/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orenlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-15T17:13:40.000Z","updated_at":"2026-04-01T11:05:13.000Z","dependencies_parsed_at":"2026-02-12T17:06:17.246Z","dependency_job_id":null,"html_url":"https://github.com/orenlab/codeclone","commit_stats":null,"previous_names":["orenlab/codeclone"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/orenlab/codeclone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fcodeclone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fcodeclone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fcodeclone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fcodeclone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orenlab","download_url":"https://codeload.github.com/orenlab/codeclone/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fcodeclone/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31448216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-development","ast","baseline","ci","clone-detection","code-quality","dead-code","deterministic-reporting","mcp","python","quality-gates","software-metrics","static-analysis"],"created_at":"2026-01-17T22:02:09.026Z","updated_at":"2026-04-05T20:02:16.803Z","avatar_url":"https://github.com/orenlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/codeclone-wordmark-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/codeclone-wordmark.svg\"\u003e\n    \u003cimg alt=\"CodeClone\" src=\"docs/assets/codeclone-wordmark.svg\" width=\"320\"\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStructural code quality analysis for Python\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/codeclone/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/codeclone.svg?style=flat-square\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/codeclone/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/codeclone.svg?style=flat-square\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/orenlab/codeclone/actions/workflows/tests.yml\"\u003e\u003cimg src=\"https://github.com/orenlab/codeclone/actions/workflows/tests.yml/badge.svg?branch=main\u0026style=flat-square\" alt=\"Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml\"\u003e\u003cimg src=\"https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml/badge.svg?style=flat-square\" alt=\"Benchmark\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/codeclone/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/codeclone.svg?style=flat-square\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/orenlab/codeclone\"\u003e\u003cimg src=\"https://img.shields.io/badge/codeclone-85%20(B)-green\" alt=\"codeclone 85 (B)\"\u003e\u003c/a\u003e\n  \u003ca href=\"#license\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MPL--2.0-brightgreen?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nCodeClone provides deterministic structural code quality analysis for Python.\nIt detects architectural duplication, computes quality metrics, and enforces CI gates — all with **baseline-aware\ngovernance** that separates **known** technical debt from **new** regressions.\nAn optional MCP interface exposes the same canonical analysis pipeline to AI agents and IDEs.\n\nDocs: [orenlab.github.io/codeclone](https://orenlab.github.io/codeclone/) ·\nLive sample report:\n[orenlab.github.io/codeclone/examples/report/](https://orenlab.github.io/codeclone/examples/report/)\n\n\u003e [!NOTE]\n\u003e This README and docs site track the in-development `v2.0.x` line from `main`.\n\u003e For the latest stable CodeClone documentation (`v1.4.4`), see the\n\u003e [`v1.4.4` README](https://github.com/orenlab/codeclone/blob/v1.4.4/README.md)\n\u003e and the\n\u003e [`v1.4.4` docs tree](https://github.com/orenlab/codeclone/tree/v1.4.4/docs).\n\n## Features\n\n- **Clone detection** — function (CFG fingerprint), block (statement windows), and segment (report-only) clones\n- **Structural findings** — duplicated branch families, clone guard/exit divergence and clone-cohort drift (report-only)\n- **Quality metrics** — cyclomatic complexity, coupling (`CBO`), cohesion (`LCOM4`), dependency cycles, dead code,\n  health score, and report-only `Overloaded Modules` profiling\n- **Baseline governance** — separates accepted **legacy** debt from **new regressions** and lets CI fail **only** on\n  what changed\n- **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report\n- **MCP server** — optional read-only surface for AI agents and IDEs, designed as a budget-aware guided control\n  surface for agentic development\n- **VS Code extension** — preview native client for CodeClone MCP with triage-first structural review\n- **Native client surfaces** — preview Claude Desktop bundle and Codex plugin over the same canonical MCP contract\n- **CI-first** — deterministic output, stable ordering, exit code contract, pre-commit support\n- **Fast** — incremental caching, parallel processing, warm-run optimization, and reproducible benchmark coverage\n\n## Quick Start\n\n```bash\nuv tool install codeclone      # use --pre for beta\n\ncodeclone .                    # analyze\ncodeclone . --html             # HTML report\ncodeclone . --html --open-html-report  # open in browser\ncodeclone . --json --md --sarif --text # all formats\ncodeclone . --ci               # CI mode\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eMore examples\u003c/summary\u003e\n\n```bash\n# timestamped report snapshots\ncodeclone . --html --json --timestamped-report-paths\n\n# changed-scope gating against git diff\ncodeclone . --changed-only --diff-against main\n\n# shorthand: diff source for changed-scope review\ncodeclone . --paths-from-git-diff HEAD~1\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRun without install\u003c/summary\u003e\n\n```bash\nuvx codeclone@latest .\n```\n\n\u003c/details\u003e\n\n## CI Integration\n\n```bash\n# 1. Generate baseline (commit to repo)\ncodeclone . --update-baseline\n\n# 2. Add to CI pipeline\ncodeclone . --ci\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eWhat \u003ccode\u003e--ci\u003c/code\u003e enables\u003c/summary\u003e\nThe \u003ccode\u003e--ci\u003c/code\u003e preset equals \u003ccode\u003e--fail-on-new --no-color --quiet\u003c/code\u003e.\nWhen a trusted metrics baseline is loaded, CI mode also enables\n\u003ccode\u003e--fail-on-new-metrics\u003c/code\u003e.\n\u003c/details\u003e\n\n### GitHub Action\n\nCodeClone also ships a composite GitHub Action for PR and CI workflows:\n\n```yaml\n- uses: orenlab/codeclone/.github/actions/codeclone@main\n  with:\n    fail-on-new: \"true\"\n    sarif: \"true\"\n    pr-comment: \"true\"\n```\n\nIt can:\n\n- run baseline-aware gating\n- generate JSON and SARIF reports\n- upload SARIF to GitHub Code Scanning\n- post or update a PR summary comment\n\nAction docs:\n[.github/actions/codeclone/README.md](https://github.com/orenlab/codeclone/blob/main/.github/actions/codeclone/README.md)\n\n### Quality Gates\n\n```bash\n# Metrics thresholds\ncodeclone . --fail-complexity 20 --fail-coupling 10 --fail-cohesion 4 --fail-health 60\n\n# Structural policies\ncodeclone . --fail-cycles --fail-dead-code\n\n# Regression detection vs baseline\ncodeclone . --fail-on-new-metrics\n```\n\n### Pre-commit\n\n```yaml\nrepos:\n  - repo: local\n    hooks:\n      - id: codeclone\n        name: CodeClone\n        entry: codeclone\n        language: system\n        pass_filenames: false\n        args: [ \".\", \"--ci\" ]\n        types: [ python ]\n```\n\n## MCP Server\n\nOptional read-only MCP server for AI agents and IDE clients.\n21 tools + 10 resources — never mutates source, baselines, or repo state.\n\n```bash\nuv tool install --pre \"codeclone[mcp]\"       # or: uv pip install --pre \"codeclone[mcp]\"\n\ncodeclone-mcp --transport stdio            # local (Claude Code, Codex, Copilot, Gemini CLI)\ncodeclone-mcp --transport streamable-http  # remote / HTTP-only clients\n```\n\nDocs:\n[MCP usage guide](https://orenlab.github.io/codeclone/mcp/)\n·\n[MCP interface contract](https://orenlab.github.io/codeclone/book/20-mcp-interface/)\n\n### Native Client Surfaces\n\n| Surface                   | Location                                                                                                                     | Purpose                                            |\n|---------------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|\n| **VS Code extension**     | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=orenlab.codeclone)                                 | Triage-first structural review in the editor       |\n| **Claude Desktop bundle** | [`extensions/claude-desktop-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/claude-desktop-codeclone) | Local `.mcpb` install with pre-loaded instructions |\n| **Codex plugin**          | [`plugins/codeclone/`](https://github.com/orenlab/codeclone/tree/main/plugins/codeclone)                                     | Native discovery, two skills, and MCP definition   |\n\nAll three are thin wrappers over the same `codeclone-mcp` contract — no second analysis engine.\n\n## Configuration\n\nCodeClone can load project-level configuration from `pyproject.toml`:\n\n```toml\n[tool.codeclone]\nmin_loc = 10\nmin_stmt = 6\nbaseline = \"codeclone.baseline.json\"\nskip_metrics = false\nquiet = false\nhtml_out = \".cache/codeclone/report.html\"\njson_out = \".cache/codeclone/report.json\"\nmd_out = \".cache/codeclone/report.md\"\nsarif_out = \".cache/codeclone/report.sarif\"\ntext_out = \".cache/codeclone/report.txt\"\nblock_min_loc = 20\nblock_min_stmt = 8\nsegment_min_loc = 20\nsegment_min_stmt = 10\n```\n\nPrecedence: CLI flags \u003e `pyproject.toml` \u003e built-in defaults.\n\n## Baseline Workflow\n\nBaselines capture the current duplication state. Once committed, they become the CI reference point.\n\n- Clones are classified as **NEW** (not in baseline) or **KNOWN** (accepted debt)\n- `--update-baseline` writes both clone and metrics snapshots\n- Trust is verified via `generator`, `fingerprint_version`, and `payload_sha256`\n- In `--ci` mode, an untrusted baseline is a contract error (exit 2)\n\nFull contract: [Baseline contract](https://orenlab.github.io/codeclone/book/06-baseline/)\n\n## Exit Codes\n\n| Code | Meaning                                                                       |\n|------|-------------------------------------------------------------------------------|\n| `0`  | Success                                                                       |\n| `2`  | Contract error — untrusted baseline, invalid config, unreadable sources in CI |\n| `3`  | Gating failure — new clones or metric threshold exceeded                      |\n| `5`  | Internal error                                                                |\n\nContract errors (`2`) take precedence over gating failures (`3`).\n\n## Reports\n\n| Format   | Flag      | Default path                    |\n|----------|-----------|---------------------------------|\n| HTML     | `--html`  | `.cache/codeclone/report.html`  |\n| JSON     | `--json`  | `.cache/codeclone/report.json`  |\n| Markdown | `--md`    | `.cache/codeclone/report.md`    |\n| SARIF    | `--sarif` | `.cache/codeclone/report.sarif` |\n| Text     | `--text`  | `.cache/codeclone/report.txt`   |\n\nAll report formats are rendered from one canonical JSON report document.\n\n- `--open-html-report` opens the generated HTML report in the default browser and requires `--html`.\n- `--timestamped-report-paths` appends a UTC timestamp to default report filenames for bare report flags such as\n  `--html` or `--json`. Explicit report paths are not rewritten.\n\nThe docs site also includes live example HTML/JSON/SARIF reports generated from the current `codeclone` repository.\n\nStructural findings include:\n\n- `duplicated_branches`\n- `clone_guard_exit_divergence`\n- `clone_cohort_drift`\n\n### Inline Suppressions\n\nCodeClone keeps dead-code detection deterministic and static by default. When a symbol is intentionally\ninvoked through runtime dynamics (for example framework callbacks, plugin loading, or reflection), suppress\nthe known false positive explicitly at the declaration site:\n\n```python\n# codeclone: ignore[dead-code]\ndef handle_exception(exc: Exception) -\u003e None:\n    ...\n\n\nclass Middleware:  # codeclone: ignore[dead-code]\n    ...\n```\n\nDynamic/runtime false positives are resolved via explicit inline suppressions, not via broad heuristics.\n\n\u003cdetails\u003e\n\u003csummary\u003eCanonical JSON report shape (v2.3)\u003c/summary\u003e\n\n```json\n{\n  \"report_schema_version\": \"2.3\",\n  \"meta\": {\n    \"codeclone_version\": \"2.0.0b4\",\n    \"project_name\": \"...\",\n    \"scan_root\": \".\",\n    \"report_mode\": \"full\",\n    \"analysis_thresholds\": {\n      \"design_findings\": {\n        \"...\": \"...\"\n      }\n    },\n    \"baseline\": {\n      \"...\": \"...\"\n    },\n    \"cache\": {\n      \"...\": \"...\"\n    },\n    \"metrics_baseline\": {\n      \"...\": \"...\"\n    },\n    \"runtime\": {\n      \"analysis_started_at_utc\": \"...\",\n      \"report_generated_at_utc\": \"...\"\n    }\n  },\n  \"inventory\": {\n    \"files\": {\n      \"...\": \"...\"\n    },\n    \"code\": {\n      \"...\": \"...\"\n    },\n    \"file_registry\": {\n      \"encoding\": \"relative_path\",\n      \"items\": []\n    }\n  },\n  \"findings\": {\n    \"summary\": {\n      \"...\": \"...\"\n    },\n    \"groups\": {\n      \"clones\": {\n        \"functions\": [],\n        \"blocks\": [],\n        \"segments\": []\n      },\n      \"structural\": {\n        \"groups\": []\n      },\n      \"dead_code\": {\n        \"groups\": []\n      },\n      \"design\": {\n        \"groups\": []\n      }\n    }\n  },\n  \"metrics\": {\n    \"summary\": {},\n    \"families\": {}\n  },\n  \"derived\": {\n    \"suggestions\": [],\n    \"overview\": {\n      \"families\": {},\n      \"top_risks\": [],\n      \"source_scope_breakdown\": {},\n      \"health_snapshot\": {},\n      \"directory_hotspots\": {}\n    },\n    \"hotlists\": {\n      \"most_actionable_ids\": [],\n      \"highest_spread_ids\": [],\n      \"production_hotspot_ids\": [],\n      \"test_fixture_hotspot_ids\": []\n    }\n  },\n  \"integrity\": {\n    \"canonicalization\": {\n      \"version\": \"1\",\n      \"scope\": \"canonical_only\"\n    },\n    \"digest\": {\n      \"algorithm\": \"sha256\",\n      \"verified\": true,\n      \"value\": \"...\"\n    }\n  }\n}\n```\n\nCanonical contract: [Report contract](https://orenlab.github.io/codeclone/book/08-report/) and\n[Dead-code contract](https://orenlab.github.io/codeclone/book/16-dead-code-contract/)\n\n\u003c/details\u003e\n\n## How It Works\n\n1. **Parse** — Python source to AST\n2. **Normalize** — canonical structure (robust to renaming, formatting)\n3. **CFG** — per-function control flow graph\n4. **Fingerprint** — stable hash computation\n5. **Group** — function, block, and segment clone groups\n6. **Metrics** — complexity, coupling, cohesion, dependencies, dead code, health\n7. **Gate** — baseline comparison, threshold checks\n\nArchitecture: [Architecture narrative](https://orenlab.github.io/codeclone/architecture/) ·\nCFG semantics: [CFG semantics](https://orenlab.github.io/codeclone/cfg/)\n\n## Documentation\n\n| Topic                      | Link                                                                                                |\n|----------------------------|-----------------------------------------------------------------------------------------------------|\n| Contract book (start here) | [Contracts and guarantees](https://orenlab.github.io/codeclone/book/00-intro/)                      |\n| Exit codes                 | [Exit codes and failure policy](https://orenlab.github.io/codeclone/book/03-contracts-exit-codes/)  |\n| Configuration              | [Config and defaults](https://orenlab.github.io/codeclone/book/04-config-and-defaults/)             |\n| Baseline contract          | [Baseline contract](https://orenlab.github.io/codeclone/book/06-baseline/)                          |\n| Cache contract             | [Cache contract](https://orenlab.github.io/codeclone/book/07-cache/)                                |\n| Report contract            | [Report contract](https://orenlab.github.io/codeclone/book/08-report/)                              |\n| Metrics \u0026 quality gates    | [Metrics and quality gates](https://orenlab.github.io/codeclone/book/15-metrics-and-quality-gates/) |\n| Dead code                  | [Dead-code contract](https://orenlab.github.io/codeclone/book/16-dead-code-contract/)               |\n| Docker benchmark contract  | [Benchmarking contract](https://orenlab.github.io/codeclone/book/18-benchmarking/)                  |\n| Determinism                | [Determinism policy](https://orenlab.github.io/codeclone/book/12-determinism/)                      |\n\n## Benchmarking Notes\n\n\u003cdetails\u003e\n\u003csummary\u003eReproducible Docker Benchmark\u003c/summary\u003e\n\n```bash\n./benchmarks/run_docker_benchmark.sh\n```\n\nThe wrapper builds `benchmarks/Dockerfile`, runs isolated container benchmarks, and writes results to\n`.cache/benchmarks/codeclone-benchmark.json`.\n\nUse environment overrides to pin the benchmark envelope:\n\n```bash\nCPUSET=0 CPUS=1.0 MEMORY=2g RUNS=16 WARMUPS=4 \\\n  ./benchmarks/run_docker_benchmark.sh\n```\n\nPerformance claims are backed by the reproducible benchmark workflow documented\nin [Benchmarking contract](https://orenlab.github.io/codeclone/book/18-benchmarking/)\n\n\u003c/details\u003e\n\n## License\n\n- **Code:** MPL-2.0\n- **Documentation:** MIT\n\nVersions released before this change remain under their original license terms.\n\n## Links\n\n- **Issues:** \u003chttps://github.com/orenlab/codeclone/issues\u003e\n- **PyPI:** \u003chttps://pypi.org/project/codeclone/\u003e\n- **Licenses:** [MPL-2.0](LICENSE) · [MIT docs](LICENSE-docs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forenlab%2Fcodeclone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forenlab%2Fcodeclone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forenlab%2Fcodeclone/lists"}