Metadata-Version: 2.4
Name: codetwin
Version: 0.1.13
Summary: A code to diagram/documentation generator.
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/carlosferreyra/codetwin
Project-URL: Homepage, https://github.com/carlosferreyra/codetwin#readme
Description-Content-Type: text/markdown

# 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

### Cargo

```bash
cargo install codetwin
```

### Python (uv)

```bash
uv tool install codetwin
```

Run without installing (ephemeral):

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

### npm

```bash
npm install -g codetwin
```

> All three package managers install the same native binary. On first run the npm and PyPI wrappers
> will bootstrap the binary via the cargo-dist installer if not already present.

## Quick Start

Generate documentation for your Rust or Python project:

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

# Generate layered architecture
codetwin gen --layout layered

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

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

# Python example
codetwin 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
codetwin 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
codetwin 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
codetwin 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 uses cargo-dist to build platform binaries. After a GitHub Release is created, separate
workflows publish wrappers to PyPI (`uv tool install codetwin`) and npm (`npm install -g codetwin`)
that bootstrap the binary on first run via the cargo-dist installer.

## 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
