CodeClone Docs

Deterministic structural review for Python codebases. One canonical analysis across CI, HTML reports, IDEs, and AI agents.

CodeClone is a structural review layer for Python focused on deterministic analysis, baseline-aware governance, and review surfaces for both humans and AI-assisted workflows.

This documentation site has two complementary layers:

• Contracts Book — canonical behavioral contracts derived from code and locked tests
• Deep Dives — architecture, CFG semantics, integrations, and operational rationale

Licensing

CodeClone source code is licensed under MPL-2.0.

Documentation content under docs/ and the published docs site are licensed under MIT.

---

Start Here

New to CodeClone?

Understand the deterministic review model and governance philosophy.

• Contracts and guarantees
• Architecture map (components + ownership)
• Terminology

Integrating into CI?

Set up baseline-aware gating and deterministic review flows.

• Exit codes and failure policy
• Metrics mode and quality gates
• Baseline contract

Using IDEs or AI agents?

Understand the canonical review surfaces and MCP contract.

• MCP interface contract
• VS Code extension
• Codex plugin

Reviewing reports?

Explore the canonical report model and rendered review surfaces.

• Report contract
• HTML report rendering
• Live sample report

---

Contracts Book

Contract-first documentation derived from code and locked tests.

The Contracts Book defines:

• schemas and typed contracts
• baseline and cache semantics
• exit codes and CI behavior
• determinism guarantees
• trust and compatibility rules
• review surface contracts

Core Contracts

• Exit codes and failure policy
• Config and defaults
• Core pipeline and invariants
• Baseline contract (schema v2.1)
• Cache contract (schema v2.7)
• Report contract (schema v2.11)

Interfaces

• CLI behavior, modes, and UX
• MCP interface contract
• VS Code extension contract
• Claude Desktop bundle contract
• Codex plugin contract
• HTML report rendering contract

System Properties

• Security model and threat boundaries
• Determinism policy
• Tests as specification
• Compatibility and versioning rules

Quality Contracts

• Health Score model and evolution policy
• Metrics mode and quality gates
• Dead-code contract and test-boundary policy
• Suggestions and clone typing contract
• Reproducible Docker benchmarking
• Inline suppressions contract

---

Deep Dives

Narrative documentation covering architecture, integrations, and operational usage.

• Architecture narrative
• CFG design and semantics
• MCP integration for AI agents and clients
• VS Code extension usage guide
• Claude Desktop bundle usage guide
• Codex plugin usage guide
• SARIF integration for IDE/code-scanning use

Operational and legal

• Privacy Policy
• Terms of Use
• Docs publishing and Pages workflow

---

Reference Appendices

• Status enums and typed contracts
• Schema layouts (baseline/cache/report)
• Error catalog (contract vs internal)

---

Local Preview

Build the siteBuild the site and sample report

Validate the docs site

uv run --with mkdocs --with mkdocs-material mkdocs build --strict

Generate the live sample report into the built site

uv run --with mkdocs --with mkdocs-material mkdocs build --strict
uv run python scripts/build_docs_example_report.py --output-dir site/examples/report/live

Generated output

site/ is generated output used for local preview and GitHub Pages publishing. It is not committed to git.

GitHub Pages publishing is handled by docs.yml via a custom Actions workflow.