CodeClone Docs

This site is built with MkDocs and published to orenlab.github.io/codeclone.

It has two documentation layers:

• Contracts Book: contract-first documentation. This is the canonical source for schemas, statuses, exit codes, trust model, and determinism guarantees. Everything here is derived from code + locked tests.
• Architecture Narrative, CFG Semantics: deep-dive narrative docs (architecture and CFG semantics). These may include rationale and design intent, but must not contradict the contract book.

The published site also exposes a live sample report generated from the current repository build:

• Examples / Sample Report

Start Here

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

Core Contracts

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

Interfaces

• CLI behavior, modes, and UX
• HTML report rendering contract

System Properties

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

Quality Contracts

• 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

• Architecture narrative
• CFG design and semantics
• SARIF integration for IDE/code-scanning 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 docs site with MkDocs, then generate the 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

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