codetwin 0.1.10

# codetwin

A code-to-diagram/documentation generator in Rust.

> Status: Phase 3.1 ✅ - Multi-layout architecture generator with Rust + Python support. Generates
> documentation in multiple formats (dependency graphs, layered architecture, README summaries).

## Overview

CodeTwin transforms your codebase into visual documentation through multiple layout strategies:

- **Dependency Graph**: Shows module interdependencies
- **Layered Architecture**: Organizes code into logical layers/tiers
- **README-Embedded**: Compact summaries perfect for GitHub discovery

Perfect for architecture reviews, onboarding, and design documentation.

## Installation

### Python (uv)

Install via uv (recommended):

```bash
uv tool install codetwin
codetwin gen --help
```

Run without installing (ephemeral):

```bash
uvx codetwin --help
```

### Rust (Cargo)

You can build and run locally with Cargo (Rust toolchain required):

```bash
# From the repository root
cargo install --path .
```

Or run directly:

```bash
cargo run -- gen --help
```

## Quick Start

Generate documentation for your Rust or Python project:

```bash
# Generate dependency graph (default)
ct gen

# Generate layered architecture
ct gen --layout layered

# Generate README summary
ct gen --layout readme-embedded

# Watch mode: auto-regenerate on file changes
ct watch

# Python example
ct gen --source examples/python_sample.py
```

## Layout Options

### Dependency Graph (Default)

Shows how modules depend on each other. Ideal for understanding coupling and module relationships.

```bash
ct gen --layout dependency-graph --output docs/architecture.md
```

**Output includes**:

- Module-level dependency diagram (Mermaid)
- List of all modules with functions/structs
- Circular dependency detection

### Layered Architecture

Organizes code into logical tiers (UI, API, Business Logic, Database, etc.). Best for architecture
reviews.

```bash
ct gen --layout layered --output docs/layers.md
```

**Output includes**:

- Layer definitions with glob patterns
- Modules grouped by layer
- Inter-layer dependency diagram
- Layer responsibilities and key functions

Configure layers in `codetwin.toml`:

```toml
[[layers]]
name = "User Interface"
patterns = ["src/cli.rs", "src/ui/**"]

[[layers]]
name = "Engine"
patterns = ["src/engine.rs"]

[[layers]]
name = "Data Layer"
patterns = ["src/db/**", "src/models/**"]
```

### README-Embedded

Compact summary designed for README files. Perfect for GitHub discovery and quick onboarding.

```bash
ct gen --layout readme-embedded --output docs/architecture.md
```

**Output includes**:

- Component overview table (Module | Purpose | Key Functions)
- Dependency overview diagram (Mermaid)
- Data flow explanation (numbered steps)
- Development guide with key files and contribution guidelines

Keep output under 300 lines for easy README embedding.

## Configuration

Create `codetwin.toml` in your project root:

```toml
# Source directories to scan
source_dirs = ["src"]

# Output file for generated documentation
output_file = "docs/architecture.md"

# Layout: dependency-graph, folder_markdown, one_per_file, layered, readme-embedded
layout = "dependency-graph"

# Patterns to exclude from scanning
exclude_patterns = [
  "**/target/**",
  "**/node_modules/**",
  "**/.git/**",
  "**/tests/**"
]

# Discovery respects nested .gitignore files (and .git/info/exclude) in addition to
# exclude_patterns. The ignore rules apply to the directory they live in and below.

# Layer configuration (for layered layout)
[[layers]]
name = "Core"
patterns = ["src/lib.rs", "src/ir.rs"]

[[layers]]
name = "Engine"
patterns = ["src/engine.rs"]
```

## Development

- Rust edition: 2024
- Min Rust: 1.93+ stable
- Key deps: `tree-sitter`, `petgraph`, `serde`, `clap`

Common tasks:

```bash
# Format & lint
cargo fmt --all
cargo clippy --all-targets -- -D warnings

# Test
cargo test --all

# Release build
cargo build --release

# Watch for changes
cargo watch -x test
```

### Release Pipeline

CodeTwin treats cargo-dist binaries as the source of truth for all CLI wrappers. The GitHub Release
artifacts produced by cargo-dist are reused to populate `codetwin/_bin/` before `uv build`, so the
PyPI wheel always ships the exact same binaries that were released.

## Features

✅ **Multiple Layouts** - Choose the documentation style that fits your needs ✅ **Rust + Python
Support** - Full tree-sitter-based AST parsing ✅ **Flexible Configuration** - Control layers,
patterns, and output formats ✅ **Watch Mode** - Auto-regenerate on file changes ✅ **JSON
Export** - Structured output for tooling integration ✅ **Mermaid Diagrams** - Embedded diagrams for
visual understanding

## Repository

- GitHub: <https://github.com/carlosferreyra/codetwin>

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history and notable changes.

## License

MIT