codebase-knowledge-graph-cli/README.md

Codebase Knowledge Graph CLI

A CLI tool that analyzes codebases and generates interactive knowledge graphs showing code relationships, dependencies, and architecture. It parses source files to extract functions, classes, imports, and call hierarchies, then outputs graph visualizations for developers to understand unfamiliar codebases.

Features

• Multi-language Parser Support: Parse Python, JavaScript, Go, and Rust source files using tree-sitter
• Dependency Graph Generation: Build dependency graphs showing imports and call relationships
• Circular Dependency Detection: Detect and report circular dependencies in the codebase
• Complexity Estimation: Calculate cyclomatic complexity for functions and methods
• Graph Export: Export graphs to DOT, JSON, and PNG formats
• Interactive CLI: Rich interactive exploration with filtering, search, and navigation

Installation

pip install codebase-knowledge-graph-cli

Or install from source:

git clone <repository>
cd codebase-knowledge-graph-cli
pip install -e .

Quick Start

# Analyze a codebase and export to JSON
codegraph analyze ./my_project --format json

# Visualize the code structure
codegraph visualize ./my_project

# Check complexity
codegraph complexity ./my_project

# Analyze dependencies
codegraph deps ./my_project

# Export to various formats
codegraph export ./my_project -o graph.dot
codegraph export ./my_project -o graph.png
codegraph export ./my_project -o graph.json

Usage

analyze command

Analyze a codebase and generate knowledge graphs:

codegraph analyze [PATH] [OPTIONS]

Options:

• --language, -l: Language (python, javascript, go, rust, auto)
• --output, -o: Output file path
• --format, -f: Output format (dot, json, png)
• --verbose, -v: Enable verbose output

visualize command

Generate a tree visualization of the codebase structure:

codegraph visualize [PATH] [OPTIONS]

complexity command

Analyze cyclomatic complexity of functions and methods:

codegraph complexity [PATH] [OPTIONS]

deps command

Analyze dependencies and detect circular imports:

codegraph deps [PATH] [OPTIONS]

export command

Export the graph to various formats:

codegraph export [PATH] -o [OUTPUT] [OPTIONS]

Configuration

Create a config.yaml file to customize behavior:

parser:
  include_patterns:
    - "*.py"
    - "*.js"
    - "*.go"
    - "*.rs"
  exclude_patterns:
    - "**/test_*.py"
    - "**/node_modules/**"
    - "**/.git/**"

analysis:
  complexity_threshold: 10

output:
  default_format: json

Output Formats

DOT

Graphviz DOT format for rendering with Graphviz tools.

JSON

Structured JSON output compatible with graph viewers and data processing.

PNG/SVG

Raster and vector image formats rendered using Graphviz.

Architecture

codebase-knowledge-graph-cli/
├── src/
│   ├── parsers/           # Language parsers (Python, JS, Go, Rust)
│   ├── graph/             # Graph building with NetworkX
│   ├── analyzers/         # Dependency and complexity analysis
│   ├── exporters/         # DOT, JSON, PNG export
│   └── cli/               # Click CLI interface
├── tests/
│   ├── unit/              # Unit tests
│   └── integration/       # Integration tests
└── config.yaml            # Configuration file

Supported Languages

• Python (.py, .pyi)
• JavaScript (.js, .jsx, .mjs, .cjs)
• Go (.go)
• Rust (.rs)

Environment Variables

• CODEGRAPH_LANGUAGE_PATH: Path to tree-sitter language binaries
• CODEGRAPH_OUTPUT_DIR: Default output directory
• CODEGRAPH_VERBOSE: Enable verbose output

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pytest tests/ -v
5. Submit a pull request

License

MIT License