gograph

module

v0.0.4 Latest Latest Go to latest Published: Jul 3, 2025 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/compozy/gograph

Links

Open Source Insights

README ¶

gograph - Go Codebase Graph Analyzer

A powerful CLI tool that analyzes Go codebases and generates graph visualizations using Neo4j, designed to help LLMs better understand project structures and avoid hallucination through concrete dependency mapping.

🚀 Features

🔍 AST-based Analysis: Deep parsing of Go source code using Go's native AST parser
📊 Neo4j Integration: Stores codebase structure in a graph database for powerful querying
🏗️ Per-Project Isolation: Each project gets its own database namespace
🤖 MCP Server: Model Context Protocol integration for LLM applications
⚡ Concurrent Processing: Efficient parallel parsing of large codebases
🔧 CLI Tool: Easy-to-use command-line interface with Cobra
📝 Configurable: YAML-based configuration for project-specific settings
🏛️ Clean Architecture: Extensible design following Domain-Driven Design principles

🛡️ Project Isolation

gograph provides complete project isolation to enable multiple Go projects to coexist safely in the same Neo4j database:

Key Benefits

🏗️ Multi-Project Support: Analyze multiple projects without data conflicts
🔒 Data Isolation: Each project's data is completely isolated from others
🏷️ Unique Identifiers: User-defined project IDs ensure clear project boundaries
🚀 Performance Optimized: Database indexes on project_id for fast queries
🧹 Safe Cleanup: Clear project data without affecting other projects

How It Works

Project Initialization: Each project requires a unique project_id during setup
Data Tagging: All nodes and relationships are tagged with the project_id
Query Filtering: All operations automatically filter by project_id
Index Optimization: Database indexes ensure fast project-scoped queries

Usage Example

# Project A
cd /path/to/project-a
gograph init --project-id backend-api --project-name "Backend API"
gograph analyze

# Project B  
cd /path/to/project-b
gograph init --project-id frontend-app --project-name "Frontend App"
gograph analyze

# Both projects coexist safely in the same database
# Queries automatically filter by project_id

🛠 Installation

Prerequisites

Go 1.24 or higher
Neo4j 5.x or higher
Make (for build automation)

Install from Source

# Clone the repository
git clone https://github.com/compozy/gograph.git
cd gograph

# Install dependencies and build
make deps
make build

# Install to GOPATH (optional)
make install

Using Go Install

go install github.com/compozy/gograph/cmd/gograph@latest

Using Docker

# Pull the image
docker pull compozy/gograph:latest

# Run with volume mount
docker run -v $(pwd):/workspace compozy/gograph:latest analyze /workspace

🚀 Quick Start

Start Neo4j:

# Using Docker
make run-neo4j

# Or using Docker directly
docker run -d \
  --name gograph-neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5-community

Initialize project configuration:

gograph init --project-id my-awesome-project

Analyze your Go project:
```
gograph analyze
```

Query the graph:

gograph query "MATCH (n:Function) RETURN n.name LIMIT 10"

View the complete graph in Neo4j Browser:

# Open Neo4j Browser at http://localhost:7474
# Login with: neo4j/password
# Run this query to see the entire codebase graph:
MATCH (n) RETURN n LIMIT 500

🔍 Complete Codebase Analysis Workflow

Here's a step-by-step guide to analyze your entire codebase and visualize it in Neo4j:

1. Setup and Analysis

# Start Neo4j database
make run-neo4j

# Navigate to your Go project directory
cd /path/to/your/go/project

# Initialize gograph configuration with required project ID
gograph init --project-id my-awesome-project --project-name "My Awesome Project"

# Analyze the entire codebase (project ID is read from config)
gograph analyze . \
  --include-tests \
  --include-vendor \
  --concurrency 8

2. Access Neo4j Browser

Open your web browser and go to: http://localhost:7474
Login with:
- Username: neo4j
- Password: password

3. Essential Graph Visualization Queries

Once connected, try these queries to explore your codebase:

Complete Project Overview

// View the entire project structure
MATCH (n)
WHERE n.project_id = 'my-awesome-project'
RETURN n
LIMIT 500

Package Dependencies

// Visualize package import relationships
MATCH (p1:Package)-[:IMPORTS]->(p2:Package)
WHERE p1.project_id = 'my-awesome-project'
RETURN p1, p2

Function Call Graph

// See function call relationships
MATCH (f1:Function)-[:CALLS]->(f2:Function)
WHERE f1.project_id = 'my-awesome-project'
RETURN f1, f2
LIMIT 100

Architecture Overview

// High-level architecture view (packages and their relationships)
MATCH path = (p1:Package)-[:IMPORTS*1..2]->(p2:Package)
WHERE p1.project_id = 'my-awesome-project'
  AND p2.project_id = 'my-awesome-project'
RETURN path
LIMIT 50

Code Complexity Hotspots

// Find the most connected functions (potential complexity hotspots)
MATCH (f:Function)
WHERE f.project_id = 'my-awesome-project'
WITH f,
     size((f)-[:CALLS]->()) as outgoing_calls,
     size((f)<-[:CALLS]-()) as incoming_calls
RETURN f.name, f.package, outgoing_calls, incoming_calls,
       (outgoing_calls + incoming_calls) as total_connections
ORDER BY total_connections DESC
LIMIT 20

4. Interactive Exploration Tips

In Neo4j Browser:

Expand Nodes: Click on any node to see its properties
Follow Relationships: Double-click relationships to explore connections
Filter Results: Use the sidebar to filter node types and relationships
Adjust Layout: Use the layout options to better organize the graph
Export Views: Save interesting queries and graph views

Useful Browser Commands:

// Show node labels and relationship types
CALL db.labels()
CALL db.relationshipTypes()

// Count nodes by type
MATCH (n)
WHERE n.project_id = 'my-awesome-project'
RETURN labels(n)[0] as NodeType, count(n) as Count
ORDER BY Count DESC

// Find circular dependencies
MATCH path = (p:Package)-[:IMPORTS*2..]->(p)
WHERE p.project_id = 'my-awesome-project'
RETURN path
LIMIT 10

5. Advanced Analysis Examples

# Find unused functions
gograph query "
  MATCH (f:Function)
  WHERE f.project_id = 'my-awesome-project'
    AND NOT (f)<-[:CALLS]-()
    AND NOT f.name = 'main'
  RETURN f.name, f.package, f.file
  ORDER BY f.package, f.name
"

# Analyze test coverage by package
gograph query "
  MATCH (p:Package)
  WHERE p.project_id = 'my-awesome-project'
  OPTIONAL MATCH (p)-[:CONTAINS]->(f:File)
  WHERE f.name ENDS WITH '_test.go'
  WITH p, count(f) as test_files
  OPTIONAL MATCH (p)-[:CONTAINS]->(f2:File)
  WHERE NOT f2.name ENDS WITH '_test.go'
  RETURN p.name, count(f2) as source_files, test_files,
         CASE WHEN count(f2) > 0
              THEN round(100.0 * test_files / count(f2), 2)
              ELSE 0 END as test_ratio
  ORDER BY test_ratio DESC
"

# Find interface implementations
gograph query "
  MATCH (s:Struct)-[:IMPLEMENTS]->(i:Interface)
  WHERE s.project_id = 'my-awesome-project'
  RETURN i.name as Interface,
         collect(s.name) as Implementations,
         count(s) as ImplementationCount
  ORDER BY ImplementationCount DESC
"

# Export query results to JSON
gograph query "MATCH (n:Package) RETURN n" --format json --output packages.json

# Export to CSV for further analysis
gograph query "
  MATCH (f:Function)<-[:CALLS]-(caller)
  RETURN f.name, f.package, count(caller) as call_count
  ORDER BY call_count DESC
" --format csv --output function_popularity.csv

This workflow gives you a complete view of your codebase structure, dependencies, and relationships, making it easy to understand complex Go projects and identify architectural patterns or issues.

📖 Usage

Commands

`gograph init`

Initialize a new project configuration in the current directory.

gograph init [flags]

Flags:
  --project-id string      Unique project identifier (required)
  --project-name string    Human-readable project name (defaults to project-id)
  --project-path string    Project root path (defaults to current directory)
  --force                  Overwrite existing configuration

Examples:

# Basic initialization with required project ID
gograph init --project-id my-backend-api

# Full initialization with custom settings
gograph init \
  --project-id my-backend-api \
  --project-name "My Backend API" \
  --project-path ./src

# Force overwrite existing configuration
gograph init --project-id my-api --force

`gograph analyze`

Analyze a Go project and store the results in Neo4j. The project ID is automatically loaded from the gograph.yaml configuration file.

gograph analyze [path] [flags]

Flags:
  --path string              Path to analyze (default: current directory)
  --neo4j-uri string         Neo4j connection URI (overrides config)
  --neo4j-user string        Neo4j username (overrides config)
  --neo4j-password string    Neo4j password (overrides config)
  --project-id string        Project identifier (overrides config)
  --concurrency int          Number of concurrent workers (default: 4)
  --include-tests           Include test files in analysis
  --include-vendor          Include vendor directory

Examples:

# Analyze current directory (uses config from gograph.yaml)
gograph analyze

# Analyze specific directory with all options
gograph analyze /path/to/project --include-tests --include-vendor --concurrency 8

# Override project ID for one-time analysis
gograph analyze --project-id temporary-analysis

`gograph query`

Execute Cypher queries against the graph database.

gograph query "CYPHER_QUERY" [flags]

Flags:
  --format string    Output format: table, json, csv (default: table)
  --output string    Output file (default: stdout)
  --params string    Query parameters as JSON

`gograph serve-mcp`

Start the MCP (Model Context Protocol) server for LLM integration.

gograph serve-mcp [flags]

Flags:
  --http             Use HTTP transport (when available)
  --port int         HTTP server port (default: 8080)
  --config string    MCP configuration file

`gograph clear`

Clear project data from the database. Uses project isolation to safely remove only the specified project's data.

gograph clear [project-id] [flags]

Flags:
  --all    Clear all projects (dangerous - use with caution)
  --force  Skip confirmation prompt

Examples:

# Clear current project (reads project ID from gograph.yaml)
gograph clear

# Clear specific project by ID
gograph clear my-backend-api

# Clear with confirmation skip
gograph clear my-backend-api --force

# Clear all projects (dangerous - removes all data)
gograph clear --all --force

Safety: The clear command only removes data tagged with the specified project_id, ensuring other projects remain untouched.

Examples

# Initialize a new project
gograph init --project-id myproject --project-name "My Go Project"

# Analyze current directory (uses project ID from gograph.yaml)
gograph analyze

# Analyze specific project with custom settings
gograph analyze /path/to/project \
  --concurrency 8 \
  --include-tests

# Query function dependencies
gograph query "
  MATCH (f:Function)-[:CALLS]->(g:Function)
  WHERE f.name = 'main'
  RETURN g.name, g.package
"

# Find circular dependencies
gograph query "
  MATCH path=(p1:Package)-[:IMPORTS*]->(p1)
  RETURN path
  LIMIT 5
"

# Start MCP server for Claude Desktop
gograph serve-mcp

⚙️ Configuration

Create a gograph.yaml file in your project root:

project:
  id: my-project-id              # Required: Unique project identifier
  name: my-project               # Optional: Human-readable name (defaults to id)
  root_path: .                   # Optional: Project root path (defaults to ".")

neo4j:
  uri: bolt://localhost:7687     # Neo4j connection URI
  username: neo4j                # Neo4j username
  password: password             # Neo4j password
  database: ""                   # Optional: Database name (uses default if empty)

analysis:
  ignore_dirs:
    - .git
    - vendor
    - node_modules
    - tmp
  ignore_files:
    - "*.pb.go"
    - "*_mock.go"
  include_tests: true
  include_vendor: false
  max_concurrency: 4

mcp:
  server:
    port: 8080
    host: localhost
    max_connections: 100
  auth:
    enabled: false
    token: ""
  performance:
    max_context_size: 1000000
    cache_ttl: 3600
    batch_size: 100
    request_timeout: 30s
  security:
    allowed_paths:
      - "."
    forbidden_paths:
      - ".git"
      - "vendor"
    rate_limit: 100
    max_query_time: 30

Environment Variables

You can override configuration using environment variables:

export GOGRAPH_NEO4J_URI=bolt://localhost:7687
export GOGRAPH_NEO4J_USERNAME=neo4j
export GOGRAPH_NEO4J_PASSWORD=password
export GOGRAPH_PROJECT_ID=my-project         # Overrides config project ID
export GOGRAPH_MCP_PORT=8080

Important: The GOGRAPH_PROJECT_ID environment variable will override the project ID from your gograph.yaml file. This is useful for CI/CD environments or temporary analysis.

📊 Graph Schema

Node Types

Node Type	Description	Properties
`Package`	Go packages	`name`, `path`, `project_id`
`File`	Go source files	`name`, `path`, `lines`, `project_id`
`Function`	Function declarations	`name`, `signature`, `line`, `project_id`
`Struct`	Struct type definitions	`name`, `fields`, `line`, `project_id`
`Interface`	Interface definitions	`name`, `methods`, `line`, `project_id`
`Method`	Methods on types	`name`, `receiver`, `signature`, `project_id`
`Constant`	Constant declarations	`name`, `value`, `type`, `project_id`
`Variable`	Variable declarations	`name`, `type`, `line`, `project_id`
`Import`	Import statements	`path`, `alias`, `project_id`

Relationship Types

Relationship	Description
`CONTAINS`	Package contains file, file contains function/struct/etc.
`IMPORTS`	File imports package
`CALLS`	Function calls another function
`IMPLEMENTS`	Struct implements interface
`HAS_METHOD`	Struct/interface has method
`DEPENDS_ON`	File depends on another file
`DECLARES`	File declares function/struct/interface
`USES`	Function uses variable/constant

Example Queries

-- Find all functions in a package
MATCH (p:Package {name: "main"})-[:CONTAINS]->(f:File)-[:DECLARES]->(fn:Function)
RETURN fn.name, fn.signature

-- Find circular dependencies
MATCH path=(p1:Package)-[:IMPORTS*]->(p1)
RETURN path

-- Find most called functions
MATCH (f:Function)<-[:CALLS]-(caller)
RETURN f.name, count(caller) as call_count
ORDER BY call_count DESC

-- Find unused functions
MATCH (f:Function)
WHERE NOT (f)<-[:CALLS]-()
RETURN f.name, f.package

-- Find interface implementations
MATCH (s:Struct)-[:IMPLEMENTS]->(i:Interface)
RETURN s.name, i.name

🤖 MCP Integration

gograph provides a Model Context Protocol (MCP) server that enables LLM applications to analyze Go codebases directly.

Quick Setup with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gograph": {
      "command": "gograph",
      "args": ["serve-mcp"],
      "env": {
        "GOGRAPH_CONFIG": "/path/to/your/gograph.yaml"
      }
    }
  }
}

Available MCP Tools

Project Management:

list_projects: List all projects in the database
validate_project: Validate project existence and configuration
analyze_project: Analyze a Go project with full isolation

Code Analysis:

query_dependencies: Query project dependencies with filtering
get_function_info: Get detailed function information
list_packages: List all packages in a specific project
get_package_structure: Get detailed package structure
find_implementations: Find interface implementations
trace_call_chain: Trace function call chains

Querying & Search:

execute_cypher: Execute custom Cypher queries with project filtering
natural_language_query: Translate natural language to Cypher
get_code_context: Get code context for LLM understanding

Code Quality:

detect_code_patterns: Detect common design patterns and anti-patterns
check_test_coverage: Analyze test coverage by package
detect_circular_deps: Find circular dependencies

Verification (Anti-Hallucination):

verify_code_exists: Verify function/type existence
validate_import_path: Verify import relationships

For detailed MCP integration guide, see docs/MCP_INTEGRATION.md.

🏗 Architecture

The project follows Domain-Driven Design with clean architecture principles:

gograph/
├── cmd/gograph/           # CLI application entry point
│   ├── commands/          # Cobra command implementations
│   └── main.go           # Application main
├── engine/               # Core business logic
│   ├── core/            # Shared domain entities and errors
│   ├── parser/          # Go AST parsing domain
│   ├── graph/           # Graph operations domain
│   ├── analyzer/        # Code analysis domain
│   ├── query/           # Query building and execution
│   ├── llm/             # LLM integration (Cypher translation)
│   ├── mcp/             # Model Context Protocol server
│   └── infra/           # Infrastructure (Neo4j implementation)
├── pkg/                 # Shared utilities
│   ├── config/          # Configuration management
│   ├── logger/          # Structured logging
│   ├── progress/        # Progress reporting
│   └── testhelpers/     # Test utilities
├── test/                # Integration tests
├── testdata/            # Test fixtures
└── docs/                # Documentation

Key Design Principles

Clean Architecture: Dependencies point inward toward the domain
Domain-Driven Design: Clear domain boundaries and ubiquitous language
Interface Segregation: Small, focused interfaces
Dependency Injection: Constructor-based dependency injection
Error Handling: Structured error handling with context
Testing: Comprehensive test coverage with testify

🔧 Development

Prerequisites

Go 1.24+
Neo4j 5.x
Make
Docker (for integration tests)

Setup Development Environment

# Clone and setup
git clone https://github.com/compozy/gograph.git
cd gograph

# Install dependencies
make deps

# Start development environment (Neo4j)
make dev

# Run tests
make test

# Run linting
make lint

# Build
make build

Available Make Targets

make help                 # Show all available targets
make build               # Build the binary
make test                # Run all tests
make test-integration    # Run integration tests
make test-coverage       # Generate coverage report
make lint                # Run linter
make fmt                 # Format code
make clean               # Clean build artifacts
make dev                 # Start development environment
make ci-all              # Run full CI pipeline

Testing

The project uses comprehensive testing with:

Unit Tests: Fast, isolated tests for business logic
Integration Tests: Tests with real Neo4j database
E2E Tests: End-to-end CLI testing
Testify: Assertions and mocking framework

# Run specific test suites
make test                    # Unit tests
make test-integration        # Integration tests
make test-coverage          # Coverage report

# Run tests with verbose output
go test -v ./...

# Run specific test
go test -run TestAnalyzer ./engine/analyzer/

Code Quality

The project enforces high code quality standards:

golangci-lint: Comprehensive linting
gosec: Security analysis
nancy: Vulnerability scanning
Test Coverage: Aim for 80%+ coverage
Code Review: All changes require review

Project Standards

Follow the coding standards in .cursor/rules/
Use conventional commit messages
Ensure all tests pass before submitting PRs
Update documentation for new features
Add integration tests for new domains

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following the project standards
Add tests for new functionality
Ensure all tests pass (make ci-all)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Workflow

Issue First: Open an issue to discuss new features or bugs
Branch: Create a feature branch from main
Develop: Follow the coding standards and add tests
Test: Ensure all tests pass and coverage is maintained
Document: Update documentation for new features
Review: Submit PR for code review
Merge: Squash and merge after approval

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by:

Barista - Client-side codebase graph generator
Code2Flow - Dynamic language call graph generator
Neo4j MCP Server - Model Context Protocol integration

🔗 Links

Made with ❤️ by Pedro Nauck

Directories ¶

Path	Synopsis
cmd
gograph command
gograph/commands
engine
analyzer
core
graph
infra
llm
mcp
parser
query
pkg
config
errors
logger
mcp
progress
testhelpers

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

gograph - Go Codebase Graph Analyzer

🚀 Features

🛡️ Project Isolation

Key Benefits

How It Works

Usage Example

📋 Table of Contents

🛠 Installation

Prerequisites

Install from Source

Using Go Install

Using Docker

🚀 Quick Start

🔍 Complete Codebase Analysis Workflow

1. Setup and Analysis

2. Access Neo4j Browser

3. Essential Graph Visualization Queries

Complete Project Overview

Package Dependencies

Function Call Graph

Architecture Overview

Code Complexity Hotspots

4. Interactive Exploration Tips

5. Advanced Analysis Examples

6. Export and Share Results

📖 Usage

Commands

gograph init

gograph analyze

gograph query

gograph serve-mcp

gograph clear

Examples

⚙️ Configuration

Environment Variables

📊 Graph Schema

Node Types

Relationship Types

Example Queries

🤖 MCP Integration

Quick Setup with Claude Desktop

Available MCP Tools

🏗 Architecture

Key Design Principles

🔧 Development

Prerequisites

Setup Development Environment

Available Make Targets

Testing

Code Quality

Project Standards

🤝 Contributing

Quick Contribution Steps

Development Workflow

📄 License

🙏 Acknowledgments

🔗 Links

Directories ¶

`gograph init`

`gograph analyze`

`gograph query`

`gograph serve-mcp`

`gograph clear`