sputnicyoji/coderepomap

# coderepomap [](https://pypi.org/project/coderepomap/) [](https://www.python.org/downloads/) [](LICENSE) **English** | **[简体中文](README.zh-CN.md)** | **[日本語](README.ja.md)** `coderepomap` scans a codebase and emits three Markdown layers — module skeleton, class signatures, and reference graph — sized to roughly 1k / 2k / 3k tokens. AI agents read the layer they need instead of paging through every file, so they spend tokens on the code that matters and catch cross-file references they would otherwise miss. ## Features - **Three layers, one budget.** L1 skeleton / L2 signatures / L3 relations, each capped by a configurable token budget (`tiktoken` precise, 4-chars-per-token fallback). The renderer fills the budget — 7000-file Go projects use ~99% of the L1 cap instead of stopping at a hard limit. - **Multi-language plugin system.** C# (`tree-sitter-c-sharp`), Lua (`tree-sitter-lua`), and Go (`tree-sitter-go`) share one `LanguageParser` contract; add more by dropping in a subpackage. - **Cross-language graph.** Lua → C# references resolved through a project-wide symbol index, with ambiguous candidates surfaced rather than silently merged. - **PageRank-ranked output.** Important classes float to the top of every layer; ranking is plugin-tunable via prefix/suffix boost patterns. - **Stable Symbol IDs.** Overload-aware (`csharp:Ns.Type.Method(int,string)`), instance-vs-static distinct (`lua:mod.T#method` vs `lua:mod.T.f`), Go module-path scoped (`go:example.com/myapp/pkg/service.Service.Run`). - **Generated-code skipping (Go).** Files matching `*.pb.go` / `*_gen.go` / `*.generated.go` or carrying the `// Code generated ... DO NOT EDIT.` marker are detected and skipped — only the package symbol is kept so importers still resolve. Cuts symbol count by ~80% on typical Go service repos. - **Git hooks.** Drop-in `post-checkout` / `post-merge` regeneration; opt-in Windows toast notifier. ## Install Pick the extras that match your project: pip install coderepomap[csharp] # C# / Unity pip install coderepomap[lua] # pure Lua pip install coderepomap[go] # Go pip install coderepomap[csharp,lua,go,tiktoken] # multi-lang + precise tokens ## Quick start cd your-project repomap init --lang csharp --preset unity # or --lang lua / --lang go / --preset generic repomap generate Outputs land in `.repomap/output/`: | File | Description | |---|---| | `repomap-L1-skeleton.md` | Module-level overview (~1k tokens) | | `repomap-L2-signatures.md` | Class / function signatures (~2k tokens) | | `repomap-L3-relations.md` | Reference graph + external refs (~3k tokens) | | `repomap-meta.json` | Stats, git commit, ranker info | Point your AI agent at whichever layer matches the question. ## Configuration Single-language (`.repomap/config.yaml`): project_name: My Game lang: csharp # or: lua / go source: root_path: Assets/Scripts exclude_patterns: ["**/Editor/**", "**/Tests/**"] Multi-language (Unity + Lua): project_name: Unity + xLua langs: [csharp, lua] sources: csharp: root_path: Assets/Scripts exclude_patterns: ["**/Editor/**"] lua: root_path: Assets/LuaScripts crosslang: enabled: true lua_csharp_call_patterns: - prefix: "CS." # xLua # - prefix: "UnityEngine." # sLua / ToLua `repomap init` writes a starter file; edit before running `repomap generate`. ## Cross-language references (Lua → C#) The Lua parser emits a `csharp_call` reference for `CS.X.Y.Z` chains and for aliases (`local GO = CS.X.Y; GO.Find(...)`). The resolver: 1. Strips the configured Lua-side prefix (`CS.`, `UnityEngine.`, …). 2. Tries an exact C# FQN match against the project-wide type index. 3. Falls back to the enclosing type when the chain ends in a method name. 4. Falls back to a project-wide short-name lookup; unique → resolved; multiple → unresolved with `lang_meta.candidates` for L3 review. Resolved edges enter the PageRank graph; unresolved ones surface under **External References** in L3. Algorithm details: [docs/crosslang.md](docs/crosslang.md). ## CLI | Command | Flags | Description | |---|---|---| | `repomap init` | `--lang csharp\|lua\|go`, `--preset unity\|generic`, `--force` | Write `.repomap/config.yaml` | | `repomap generate` | `--verbose`, `--notify`, `--config ` | Parse sources, write L1/L2/L3/meta | | `repomap status` | — | Show last-run stats + registered language parsers | | `repomap hooks` | `--install` (default), `--uninstall`, `--with-notify` | Manage git `post-checkout` / `post-merge` regeneration | ## Claude Code skill `skills/repomap/` ships a [Claude Code](https://claude.com/claude-code) skill that drives this CLI from natural-language prompts ("generate code map", "扫一下代码结构 / 生成 repomap"). Install per [skills/README.md](skills/README.md) and the skill auto-detects C# / Lua / Go / mixed projects, runs `python -m coderepomap generate`, and summarizes the result. `python -m coderepomap` and `repomap` are interchangeable. ## How it works Source roots ─► Parser plugin ─► Symbols + References │ ▼ Cross-language resolver │ ▼ PageRank ranker (Symbol.id keyed) │ ▼ L1 / L2 / L3 markdown + meta JSON The layering keeps each step replaceable — adding a language requires only a new `LanguageParser` subclass; changing the ranking strategy doesn't touch the parsers. ## Development git clone https://github.com/sputnicyoji/coderepomap cd coderepomap python -m venv .venv && .venv/Scripts/activate # PowerShell: .venv\Scripts\Activate.ps1 pip install -e .[csharp,lua,go,tiktoken,dev] pytest tests/ Test fixtures live in `tests/fixtures/` (`csharp/`, `lua/`, `go/`, `u3d_mixed/`). The C# parser baseline (snapshot + golden markdown) is pinned in `tests/baseline/` and any change to the renderer or generator MUST keep it byte-equivalent — see `tests/generate_baseline.py` if you intentionally need to regenerate. 206 tests cover the parser plugins, ranker, cross-language resolver, CLI, packaging smoke, and end-to-end generator runs for each language.