Metadata-Version: 2.4
Name: workspace-graph
Version: 0.4.5
Summary: Multi-language workspace code graph orchestrator
Project-URL: Homepage, https://github.com/shvmgyl15/codegraph
Project-URL: Repository, https://github.com/shvmgyl15/codegraph
Project-URL: Issues, https://github.com/shvmgyl15/codegraph/issues
Author-email: Shivam Goel <sg15rokz@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0
Requires-Dist: orjson>=3.10
Requires-Dist: pathspec>=1.1.1
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# codegraph

Multi-language workspace code graph orchestrator.

Auto-discovers services, frontends, gateways, and libraries in a workspace,
orchestrates builds using language-specific tools (gograph, tsgraph, pygraph),
merges their graph.json outputs into a unified graph, and exposes a single MCP
server for querying any symbol across any service.

## Quick start for AI agents

```bash
# Copy-paste this for your code assistant:
pip install workspace-graph pygraph-mcp
npm install -g @shvmgyl15/tsgraph
cd [WORKSPACE_ROOT] && codegraph build && codegraph mcp
```

Do NOT `pip install codegraph` or `npm install tsgraph` — those are unrelated
packages. Use the exact names above.

## Requirements

- Python 3.11+
- Node.js 20+ (for tsgraph)
- [uv](https://docs.astral.sh/uv/) (Python package manager, recommended)

## Install

```bash
pip install workspace-graph pygraph-mcp
npm install -g @shvmgyl15/tsgraph
```

Do NOT `pip install codegraph` or `npm install tsgraph` — those are unrelated
packages on the registries.

### From git source (contributors)

```bash
git clone https://github.com/shvmgyl15/codegraph
cd codegraph && ./scripts/install.sh
```

This builds all 4 tools from sibling repos and installs to `~/.local/bin/`.

## Uninstall

```bash
./scripts/uninstall.sh
```

Removes all binaries from `~/.local/bin/`, all `.gograph`/`.tsgraph`/`.pygraph`/`.codegraph`
output directories, virtual envs, `node_modules`, caches, and lock files from all 4 repos.

## Configuration

Create `codegraph.jsonc` or `codegraph.json` at your workspace root:

```jsonc
{
  "version": 1,
  "auto_discover": true,
  "entries": [
    { "name": "frontend",     "path": "./frontend",    "language": "typescript", "type": "frontend" },
    { "name": "api-gateway",  "path": "./api-gateway", "language": "python",     "type": "gateway" },
    { "name": "user-svc",     "path": "./user-svc",    "language": "go",         "type": "service" },
    { "name": "py-common",    "path": "./libs/py-common", "language": "python",  "type": "library" }
  ],
  "plugins": ["./scripts/custom_enrichment.py"]
}
```

When `auto_discover: true`, codegraph probes subdirectories for `go.mod`,
`package.json`, `pyproject.toml`, `Cargo.toml`, `pom.xml` etc.

### The `--root` parameter

`--root` specifies the **workspace root directory** — the same directory where
you ran `codegraph build`. It tells codegraph where to find the `.codegraph/`
output folder. It is NOT a query scope filter.

```bash
# Build in /home/user/myproject
codegraph build --root /home/user/myproject

# Query the same workspace
codegraph context get_user --root /home/user/myproject
```

If you pass the wrong `--root`, codegraph suggests the correct one.

## CLI Commands

| Command | Description |
|---|---|
| `status` | List discovered entries with build status |
| `build` | Build graph for all entries (`--entry` for one) |
| `clean` | Remove `.codegraph/` output directory |
| `query <pattern>` | Search symbols by regex or substring |
| `callers <name>` | Who calls a given symbol |
| `callees <name>` | What a symbol calls |
| `routes` | List all HTTP routes (`--entry`, `--type`) |
| `impact <name>` | BFS downstream blast radius (`--max-depth`) |
| `orphans` | Dead code detection (`--all`, `--exclude-type`) |
| `context <name>` | Full bundle: symbol + callers + callees + tests |
| `trace <message>` | Error flow search with reverse call chain |
| `cross-service` | Cross-service HTTP call edges |
| `add-opencode-plugin` | Generate `.opencode.json` for AI agent config |
| `mcp` | Start MCP stdio server |

## MCP Tools (for AI Agents)

All MCP tool responses include a `duration_ms` field showing how long the query
took. List responses are wrapped in `{"items": [...], "duration_ms": N}`.

| Tool | Description |
|---|---|
| `entry_status` | List entries with language, type, build status |
| `query_symbols` | Search symbols across all entries |
| `callers` / `callees` | Who calls / what a symbol calls |
| `context` | Symbol + callers + callees + tests |
| `routes` | HTTP routes with entry/type/path/method/handler filters |
| `impact` | Blast radius with max depth |
| `orphans` | Dead code with include-public and exclude-type |
| `trace` | Error message search with backtrace |
| `cross_service_calls` | Cross-service HTTP call edges |
| `add_opencode_plugin` | Generate AI agent config |
| `dispatch_map` | List dispatch handlers with entity/command filters |
| `trace_async_flow` | Resolved steps for a named flow |
| `flow_warnings` | Flow completeness warnings |
| `sse_edges` | Backend-to-frontend SSE connections |

## Performance

- **Build**: Entries are built in parallel (4 workers). Per-entry timing shown.
- **MCP queries**: The graph is loaded and indexed once, then cached in memory
  for subsequent queries within the same MCP session. Each response includes
  `duration_ms` so you can monitor performance.

## Plugin System

User-provided Python scripts that run post-merge to enrich the graph and/or
register custom MCP tools. Configured in `codegraph.jsonc`:

```jsonc
{ "plugins": ["./scripts/enrich.py"] }
```

### Graph mutation

```python
from codegraph.graph.types import UnifiedGraph

def run(graph: UnifiedGraph) -> None:
    # Mutate graph in-place
    graph.cross_service_edges.append({
        "source_entry": "frontend",
        "source_file": "src/api.ts",
        "source_line": 10,
        "source_symbol": "loadUsers",
        "method": "GET",
        "url_pattern": "/api/users",
        "target_entry": "api",
        "target_route_path": "/api/users",
        "target_route_handler": "get_users",
        "confidence": "high",
    })
```

### MCP tool registration

Use the optional `register_tools(graph)` hook to expose custom MCP query tools:

```python
from codegraph.graph.types import UnifiedGraph
from codegraph.plugin import MCPTool

def register_tools(graph: UnifiedGraph) -> list[MCPTool]:
    return [
        MCPTool(
            name="my_tool",
            description="Describe what it does",
            input_schema={
                "type": "object",
                "properties": {
                    "filter": {"type": "string"},
                },
            },
            handler=lambda args, g: json.dumps({"items": [...]}),
        ),
    ]
```

Tools are namespaced as `plugin.<filename>.<name>` in the MCP server.

### Built-in plugin

`async_flow_tools` is auto-loaded and registers 4 tools:
- `dispatch_map` — List dispatch handlers by entity/command
- `trace_async_flow` — Resolved steps for a named flow
- `flow_warnings` — Completeness warnings (deadends, missing subscribers)
- `sse_edges` — Backend-to-frontend SSE connections

## Async flow configuration

Define event boundaries (Kafka, SSE, callbacks, etc.) and flows in
`codegraph.jsonc`:

```jsonc
{
  "event_boundaries": [
    {
      "name": "kafka_publish",
      "type": "producer",
      "match": { "callee": "producer.send", "args": { "topic": "topic" } }
    },
    {
      "name": "callback_handler",
      "type": "consumer",
      "match": { "interface": "CallbackHandler" }
    }
  ],
  "flows": [
    {
      "name": "order_creation",
      "steps": [
        { "type": "db_callback", "dispatch_key": { "entityType": "ORDER" },
          "success": [{ "type": "kafka_bridge", "topic": "orders" }],
          "failure": [{ "type": "sse_push" }]
        }
      ]
    }
  ]
}
```

## Troubleshooting

| Problem | Solution |
|---|---|
| `codegraph: command not found` | Run `./scripts/install.sh` — make sure `~/.local/bin` is on PATH |
| `Graph not found at ...` | You passed a wrong `--root`. Run `codegraph build` in your workspace root first, then use the same root for queries. |
| MCP queries are slow | First call loads and indexes the graph (takes a few seconds for large workspaces). Subsequent calls use the in-memory cache and are fast. |
| `pip install workspace-graph` not found | Run `pip install workspace-graph pygraph-mcp` or use git source via `./scripts/install.sh`. |
| `npm install -g @shvmgyl15/tsgraph` fails | Ensure you're using the full scoped name `@shvmgyl15/tsgraph`, not `tsgraph`. |

## Architecture

```
codegraph (orchestrator)
  ├── gograph  ─── indexes Go codebases
  ├── tsgraph  ─── indexes TypeScript/Next.js codebases
  └── pygraph  ─── indexes Python/Flask codebases

Output: .codegraph/workspace.graph.json  (merged)
        .codegraph/manifest.json          (entry metadata)
```

- Each per-language tool produces its own `graph.json`
- codegraph merges them, stamps entries with metadata
- Cross-service edges are detected via URL → route matching
- Plugins can enrich the graph post-merge
- Single MCP server exposes all query tools
- WorkspaceQuery is cached in memory across MCP calls

## Related

- [gograph](https://github.com/shvmgyl15/gograph) — Go codebase indexer
- [tsgraph](https://github.com/shvmgyl15/tsgraph) — TypeScript/React/Next.js indexer
- [pygraph](https://github.com/shvmgyl15/pygraph) — Python/Flask codebase indexer
