{"id":51065701,"url":"https://github.com/usuginus/go-rpcatlas","last_synced_at":"2026-06-23T06:30:45.474Z","repository":{"id":355803762,"uuid":"1229660466","full_name":"usuginus/go-rpcatlas","owner":"usuginus","description":"Static RPC flow maps for Go codebases. Source-only summaries for review, CI, and AI.","archived":false,"fork":false,"pushed_at":"2026-05-25T07:01:48.000Z","size":175,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T07:23:32.098Z","etag":null,"topics":["ai","ast","code-review","developer-tools","github-actions","go","golang","grpc","rpc","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usuginus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-05T09:08:03.000Z","updated_at":"2026-05-25T07:01:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/usuginus/go-rpcatlas","commit_stats":null,"previous_names":["usuginus/calltrail-go","usuginus/go-rpcatlas"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/usuginus/go-rpcatlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usuginus%2Fgo-rpcatlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usuginus%2Fgo-rpcatlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usuginus%2Fgo-rpcatlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usuginus%2Fgo-rpcatlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usuginus","download_url":"https://codeload.github.com/usuginus/go-rpcatlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usuginus%2Fgo-rpcatlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34678932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ast","code-review","developer-tools","github-actions","go","golang","grpc","rpc","static-analysis"],"created_at":"2026-06-23T06:30:43.874Z","updated_at":"2026-06-23T06:30:45.468Z","avatar_url":"https://github.com/usuginus.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-rpcatlas\n\n[![CI](https://github.com/usuginus/go-rpcatlas/actions/workflows/ci.yaml/badge.svg)](https://github.com/usuginus/go-rpcatlas/actions/workflows/ci.yaml)\n\nAI-ready context for explaining Go RPC flows.\n\n`go-rpcatlas` generates static RPC/API flow summaries that help AI agents and\nreviewers understand Go code faster. It reads source code, finds handlers, and\nproduces deterministic Markdown or JSON for code explanation, review, onboarding,\nand CI.\n\nIt does not boot the service, send traffic, or require runtime tracing.\n\nhttps://github.com/user-attachments/assets/fb778bb9-be8a-4b7b-8bb1-4cdcd8bd7da3\n\n## Quick Example\n\n### 1. List RPC entry points\n\n```bash\nrpcatlas ./... --list\n```\n\n```markdown\n| rpc | handler | location |\n| --- | --- | --- |\n| `GetFoo` | `Server.GetFoo` | `examples/grpc-basic/handler.go:19` |\n```\n\nUse this first when you do not know the exact handler name.\n\n### 2. Inspect one RPC\n\n```bash\nrpcatlas ./... --rpc GetFoo --depth 5\n```\n\nThe Markdown report starts with the entry point, then shows the call tree and\nthe places where static resolution mattered.\n\n```markdown\n## GetFoo\n\n### execution summary\n\n- kind: `grpc`\n- handler: `Server.GetFoo` (examples/grpc-basic/handler.go:19)\n- request: `*GetFooRequest`\n- response: `*FooResponse`\n- layers:\n  - usecase: 1 call\n  - repository: 1 call\n  - converter: 1 call\n- call resolution:\n  - interface calls: 1\n  - function values: 0\n- control flow:\n  - conditional paths: 0\n  - keyed dispatches: 0\n\n### call tree\n\n- [handler] `Server.GetFoo` (examples/grpc-basic/handler.go:19)\n  - [usecase] `s.fooUsecase.GetFoo` (examples/grpc-basic/handler.go:20)\n    - [usecase] `fooUsecase.GetFoo` (examples/grpc-basic/usecase.go:19)\n      - [repository] `u.repositories.Foos.FindFoo` (examples/grpc-basic/usecase.go:20)\n        - [repository] `fooRepository.FindFoo` (examples/grpc-basic/repository.go:12)\n  - [converter] `s.fooConverter.ToResponse` (examples/grpc-basic/handler.go:24)\n    - [converter] `fooConverter.ToResponse` (examples/grpc-basic/converter.go:5)\n\n### call resolution\n\n#### interface calls\n\n| call | interface | candidates | resolution |\n| --- | --- | --- | --- |\n| `s.fooUsecase.GetFoo` (examples/grpc-basic/handler.go:20) | `FooUsecase` | `fooUsecase.GetFoo` (examples/grpc-basic/usecase.go:19) expanded | single expanded |\n```\n\n### 3. Use the output\n\n- Give it to an AI agent before asking it to explain, review, or modify a request flow.\n- Paste Markdown into a pull request, issue, or review note.\n- Upload it as a CI artifact.\n- Use JSON when you want to build automation around the same analysis data.\n\n## Why rpcatlas?\n\n| Problem | How rpcatlas helps |\n| --- | --- |\n| \"Where does this RPC go?\" | Shows a handler-centered call tree with source locations. |\n| \"What should I read first?\" | Groups calls by layer, such as `usecase`, `repository`, and `external_client`. |\n| \"Can AI explain this code?\" | Produces deterministic context before the agent reads every file. |\n| \"Can AI review this flow?\" | Fits naturally into review prompts and PR comments. |\n| \"Can I run it in CI?\" | Runs from source without booting the service or attaching a tracer. |\n| \"Is it safe to add to CI?\" | Has no third-party module dependencies and keeps the supply-chain surface minimal. |\n| \"Where is static resolution important?\" | Surfaces interface calls, function values, branches, and keyed dispatches. |\n\n## Lightweight by Design\n\n`go-rpcatlas` is built with Go's standard AST and type-analysis packages. The\nsmall dependency surface keeps installs simple and audits straightforward.\n\n## Install\n\n```bash\ngo install github.com/usuginus/go-rpcatlas/cmd/rpcatlas@latest\n```\n\nIf `rpcatlas` is installed but your shell cannot find it, make sure your Go\nbinary directory is on `PATH`:\n\n```bash\nexport PATH=\"$(go env GOPATH)/bin:$PATH\"\n```\n\nYou can also use the install script:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/usuginus/go-rpcatlas/main/install.sh | sh\n```\n\nPin a release or install to a custom directory:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/usuginus/go-rpcatlas/main/install.sh \\\n  | VERSION=v1.0.0 INSTALL_DIR=/usr/local/bin sh\n```\n\n## GitHub Action\n\nThis repository ships a composite action. It installs the CLI from the same ref\nas the action and runs it in your workflow.\n\n```yaml\nname: rpcatlas\n\non:\n  pull_request:\n\njobs:\n  rpcatlas:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: usuginus/go-rpcatlas@v1.0.0\n        with:\n          path: ./...\n          config: .rpcatlas.yaml\n          rpc: GetFoo\n          depth: \"5\"\n          format: markdown\n          output-file: rpcatlas.md\n\n      - uses: actions/upload-artifact@v4\n        with:\n          name: rpcatlas\n          path: rpcatlas.md\n```\n\n## AI Agent Skill\n\nThis repository includes an optional agent skill at\n[skills/rpcatlas/SKILL.md](skills/rpcatlas/SKILL.md).\n\nUse it when an AI agent needs to explain a Go RPC/API handler, review a request\nflow, or prepare compact source context before reading a large codebase.\n\n## Configuration\n\n`go-rpcatlas` works without configuration, but `.rpcatlas.yaml` makes the output\nmore useful for real projects.\n\nFor most repositories, put `.rpcatlas.yaml` at the repository root. Local CLI\nruns automatically discover it by walking up from the target path:\n\n```bash\nrpcatlas ./... --rpc GetFoo --depth 5\n```\n\nIn CI, pass `config: .rpcatlas.yaml` explicitly, as shown in the GitHub Action\nexample above. For monorepos, point `path` and `config` at the same service.\n\n```yaml\n# Optional package presets.\npresets:\n  - generic\n\n# Calls that should be hidden from the call tree.\nignore_calls:\n  packages:\n    - fmt\n    - log\n  names:\n    - Error\n\n# Output sections. The name is emitted as-is.\nlayers:\n  - name: application\n    match:\n      call_name_contains:\n        - usecase\n        - service\n      receiver_type_contains:\n        - usecase\n        - service\n      file_path_contains:\n        - /usecase/\n        - /service/\n\n  - name: repository\n    match:\n      call_name_contains:\n        - repository\n      receiver_type_contains:\n        - repository\n      file_path_contains:\n        - /repository/\n\n  - name: external_client\n    match:\n      call_name_contains:\n        - client\n      receiver_type_contains:\n        - client\n      file_path_contains:\n        - /client/\n        - /gateway/\n```\n\nSee [rpcatlas.example.yaml](rpcatlas.example.yaml) for a fuller starting point.\n\n## Output Modes\n\n- `--format markdown`: optimized for pull requests, issues, docs, and AI prompts.\n- `--format json`: the same analysis data in a machine-readable shape.\n\n## Public Sample\n\nFor a public, non-domain-specific target, try\n[evrone/go-clean-template](https://github.com/evrone/go-clean-template):\n\n```bash\ngit clone https://github.com/evrone/go-clean-template.git /tmp/go-clean-template\nrpcatlas /tmp/go-clean-template --list\n```\n\n## Limits\n\n`go-rpcatlas` is intentionally lightweight. It relies on Go AST and type\ninformation plus project-configurable heuristics; it is not a full SSA analyzer\nor runtime tracer.\n\nThat means it can produce a concise, deterministic summary quickly, but it may\nmiss calls that depend on complex runtime wiring, reflection, generated dynamic\nregistries, or build tags that are not active in the current environment.\n\nAlways verify critical behavior by reading the source code.\n\n## Development\n\n```bash\ngo test ./...\ngo build -o /tmp/rpcatlas ./cmd/rpcatlas\n/tmp/rpcatlas ./examples/grpc-basic --rpc GetFoo --depth 4\n```\n\nThe CI workflow checks formatting, unit tests, and coverage summary output.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusuginus%2Fgo-rpcatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusuginus%2Fgo-rpcatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusuginus%2Fgo-rpcatlas/lists"}