Zero-config, language-agnostic CLI that turns any git repository into high-quality visual documentation — useful from first
git cloneto ongoing refactoring.
Status: the first working slice inventories Rust workspace packages and declared local dependencies, then generates a Markdown overview with linked crate pages. Deeper source parsing and the legacy language drivers remain scaffolded.
For the current development version, use the checkout commands below. Registry packages may represent older releases; the current workspace is not ready for crates.io publication because its internal product dependencies are private and path-only. npm and PyPI wrapper generation is configured, but a successful wrapper build does not establish release availability.
# Inspect this workspace without writing files.
cargo run -p codetwin -- inspect . --json
# Generate the overview and linked crate pages.
cargo run -p codetwin -- visualize . --output docs/code
# Analyze another checkout; relative output is rooted in its Cargo workspace.
cargo run -p codetwin -- visualize /path/to/repository --output docs/code
Open the generated CodeTwin overview to explore this repository. Each crate page shows its targets, manifest/source links, local dependencies, and dependents. Isolated workspace members are included. Dependency arrows point from dependent to dependency; dev/build dependencies, aliases, optional flags, and target conditions retain their qualifications.
inspect without --json prints a concise inventory. Cargo must be available; analysis uses
cargo metadata --no-deps --offline --locked without compiling the analyzed repository or fetching
dependencies. The graph includes workspace members and their declared local dependencies,
not external packages, resolved feature activation, or runtime calls. Members and target sources
must be inside the workspace root. JSON paths are relative to that root.
visualize defaults to docs/code, relative to the analyzed Cargo workspace root, and generates
index.md plus detail pages under crates/. Repeated runs refresh pages bearing CodeTwin’s ownership comment.
Conflicts with user-authored files, non-directory parents, and symlink destinations are refused
before writing; unrelated files are preserved. Source links are relative to each page and URL-encoded.
visualize --json fails with guidance to use inspect --json.
See the smoke tests and acceptance cases for reproducible checks.
The existing command routes remain available; their source extraction is still scaffolded:
# Zero-config run — writes docs/architecture.md with the project-overview layout.
codetwin gen
# Inspect what CodeTwin detected.
codetwin list --drivers --layouts
# Re-render on every filesystem change.
codetwin gen --watch
# Dump the intermediate representation as JSON.
codetwin gen --dump-ir > codemodel.json
snapshot and diff remain registered compatibility routes, but capture and comparison are
not implemented. init currently overwrites configuration even without --force; gen --save
and --multi-file are incomplete. Legacy drivers emit empty models.
Global flags: --verbose, --quiet, -C/--cwd, --json where supported.
For inspect and visualize, -C sets the base for resolving the repository path.
Legacy commands retain their existing working-directory behavior; invoking no subcommand still runs gen.
| Name | Audience | Status |
|---|---|---|
project-overview |
Developer who just cloned the repo | Scaffolded |
architecture-map |
Architect reviewing the system | Scaffolded |
c4 |
C4-model consumers | Phase 6.a |
metrics |
Coupling / circular-dep reporting | Phase 6.b |
codetwin list --layouts prints the live registry.
codetwin.toml)This configuration applies to the legacy commands. inspect and visualize use their
repository and output arguments.
Everything is optional. See the checked-in codetwin.toml for an annotated
starting point.
source_dirs = ["src"]
output_file = "docs/architecture.md"
layout = "project-overview"
format = "markdown" # "html" is reserved for Phase 7
exclude_patterns = ["**/target/**", "**/node_modules/**"]
# Override auto-detected drivers:
# drivers = ["rust", "python"]
[[layers]]
name = "CLI"
patterns = ["src/cli/**"]
Requires Rust 1.93+ (edition 2024).
cargo xtask check # formatting, compilation, and Clippy
cargo xtask test # check, then workspace tests
cargo xtask build # test, then release build
cargo run -p codetwin -- list
build includes test, and test includes check; choose the command needed for the task.
CI runs cargo xtask ci, which includes tests and workspace documentation. These commands use
installed tools without installing or upgrading them.
Product crates live under crates/; private repository automation lives under tools/xtask.
Use cargo xtask --help and cargo xtask scaffold --help to inspect available commands. Add
crates only when a roadmap-backed responsibility needs a separate interface; the existing
empty crates remain transitional until the system design is settled.
cargo xtask scaffold crate <semantic-name> --dry-run
cargo xtask scaffold ci --dry-run
cargo xtask doctor
Scaffolds refuse to overwrite conflicting user-owned files. Optional tool installation is
explicit: cargo xtask tools sync <group> installs the latest stable tools under .xtask/tools
and updates the shared stable Rust toolchain. CodeTwin’s declared MSRV remains 1.93.
See CONTRIBUTING.md for the development workflow and
crates/codetwin-legacy/tests/README.md for the testing
cheatsheet. The template snapshot and migration decisions are recorded in
docs/TEMPLATE_MIGRATION.md.
cargo release → git-cliff → cargo-dist, with PyPI and npm wrapper workflows publishing
after GitHub Releases. This is out of roadmap scope.
ROADMAP.mddocs/CONSOLIDATION.mdCHANGELOG.mdMIT