grid-analyzer 0.1.1
Understand any codebase in minutes with local-first AI
License: MIT
Requires Python: >=3.8
Keywords: code-analysis, ai, rag, codebase-understanding, developer-tools

# GRID Analyzer

> Understand any codebase in minutes with local-first AI

[![PyPI version](https://badge.fury.io/py/grid-analyzer.svg)](https://pypi.org/project/grid-analyzer/)
[![Python Versions](https://img.shields.io/pypi/pyversions/grid-analyzer.svg)](https://pypi.org/project/grid-analyzer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

GRID Analyzer is a privacy-first command-line tool that uses local AI models to help you understand unfamiliar codebases. Index, query, and visualize relationships—all without sending your code to external APIs.

## ✨ Features

- 🔒 **Privacy-First**: All analysis happens locally. Your code never leaves your machine.
- 🚀 **Fast Indexing**: Analyze large codebases (100K+ files) in minutes
- 💬 **Natural Language Queries**: Ask questions in plain English
- 🗺️ **Visual Mapping**: Generate interactive relationship graphs
- 🎯 **Pattern Detection**: Automatically detect architectural patterns
- 🔍 **Multi-Language Support**: Python, JavaScript, TypeScript, Java, C++, Go, Rust, and more
- 📦 **Zero Configuration**: Works out of the box

## 🚀 Quick Start

### Installation

```bash
pip install grid-analyzer
```

### Running GRID Analyzer

**Option 1: Direct command (recommended)**
```bash
grid --help
grid analyze /path/to/codebase
```

**Option 2: Python module (if `grid` command not found)**
```bash
python -m grid_analyze_cli --help
python -m grid_analyze_cli analyze /path/to/codebase
```

> **Note**: If the `grid` command isn't found, ensure Python's Scripts directory is in your PATH, or use the `python -m grid_analyze_cli` syntax which always works.

### Basic Usage

```bash
# 1. Index your codebase
grid analyze /path/to/codebase

# 2. Ask questions
grid query "Where is user authentication handled?"
grid query "What files connect to the database?"
grid query "How does the payment system work?"

# 3. Generate visual map
grid map --output relationships.html
```

## 📖 Documentation

### Commands

#### `analyze` - Index a codebase

```bash
grid analyze <directory> [options]

Options:
  --language LANG       Primary language (auto-detected if not specified)
  --exclude PATTERN     Exclude patterns (can be repeated)
  --output DIR          Output directory (default: .grid)
  -v, --verbose         Verbose output
```

**Examples:**

```bash
# Analyze current directory
grid analyze .

# Analyze with exclusions
grid analyze ~/projects/myapp --exclude "*.test.js" --exclude "dist"

# Specify primary language
grid analyze . --language python
```

#### `query` - Ask questions about your code

```bash
grid query "<question>" [options]

Options:
  --format FORMAT       Output format: text, json, markdown (default: text)
  --limit N             Maximum results (default: 10)
```

**Examples:**

```bash
# Ask natural language questions
grid query "Where is the API authentication middleware?"
grid query "What functions handle file uploads?"
grid query "Show me all database models"

# Get JSON output for scripting
grid query "list all API endpoints" --format json

# Limit results
grid query "find error handlers" --limit 5
```

#### `map` - Generate relationship graphs

```bash
grid map --output <file> [options]

Options:
  --output FILE         Output file (.svg, .pdf, .html, .json)
  --style STYLE         Graph style: default, compact, detailed
  --focus MODULE        Focus on specific module or file
```

**Examples:**

```bash
# Generate interactive HTML visualization
grid map --output codebase.html

# Focus on specific module
grid map --output auth-system.html --focus "src/auth"

# Export as JSON for custom processing
grid map --output graph.json
```

#### `config` - Manage configuration

```bash
grid config <action> [key] [value]

Actions:
  show          Show all configuration
  get KEY       Get specific value
  set KEY VAL   Set configuration value
  reset         Reset to defaults
```

**Examples:**

```bash
# View configuration
grid config show

# Change settings
grid config set max_file_size_mb 20
grid config set use_color true

# Reset to defaults
grid config reset
```

#### `license` - Manage license

```bash
grid license <action> [key]

Actions:
  activate KEY  Activate paid license
  show          Show license information
  deactivate    Deactivate license
```

**Examples:**

```bash
# Activate Professional license
grid license activate GRID-PRO-XXXXXXXXXXXX

# Check current tier
grid license show

# Deactivate and return to Free tier
grid license deactivate
```

## 💰 Pricing

| Tier | Price | Max Files | Features |
|------|-------|-----------|----------|
| **Free** | $0 | 10,000 | Local analysis, basic queries |
| **Professional** | $20/mo | Unlimited | Advanced queries, relationship mapping |
| **Team** | $100/mo | Unlimited | Collaboration, shared indexes, SSO |
| **Enterprise** | Contact us | Unlimited | On-premise, custom training, SLA |

👉 **Upgrade at**: https://grid-analyzer.com/pricing

## 🔧 Advanced Usage

### Integrate with CI/CD

```bash
# Generate codebase report in CI pipeline
grid analyze . --output /artifacts/grid-index
grid map --output /artifacts/architecture.html
grid query "list all TODO comments" --format json > /artifacts/todos.json
```

### Export Data

```bash
# Export relationship data
grid map --output graph.json

# Query results as JSON
grid query "find all API endpoints" --format json > endpoints.json
```

### Configuration File

GRID Analyzer stores configuration in `~/.grid/config.json`:

```json
{
  "language": "auto",
  "exclude_patterns": [
    "*.git",
    "node_modules",
    "venv"
  ],
  "max_file_size_mb": 10,
  "use_color": true,
  "check_updates": true
}
```

## 🎯 Use Cases

### 1. **Onboarding New Developers**

```bash
# Create onboarding documentation
grid analyze .
grid map --output architecture.html
grid query "what are the main components?" > onboarding-guide.md
```

### 2. **Code Reviews**

```bash
# Understand changes in context
grid analyze /path/to/feature-branch
grid query "what does this PR change?"
grid map --focus "src/changed-module"
```

### 3. **Debugging Legacy Code**

```bash
# Find relevant code quickly
grid query "where are database connections created?"
grid query "what handles the payment webhook?"
grid map --focus "src/payments" --output payment-flow.html
```

### 4. **Documentation Generation**

```bash
# Auto-generate architecture docs
grid analyze .
grid map --output docs/architecture.html --style detailed
grid query "list all public APIs" --format markdown > docs/api.md
```

### 5. **Security Audits**

```bash
# Find security-sensitive code
grid query "where is user input sanitized?"
grid query "what files handle authentication?"
grid query "find all SQL query builders"
```

### 6. **Refactoring Planning**

```bash
# Understand dependencies before refactoring
grid map --focus "legacy-module" --output dependencies.html
grid query "what depends on the old API?"
```

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# Development setup
git clone https://github.com/yourusername/grid-analyzer.git
cd grid-analyzer
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
```

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🐛 Bug Reports

Found a bug? [Open an issue](https://github.com/yourusername/grid-analyzer/issues/new) with:
- Steps to reproduce
- Expected vs actual behavior
- GRID version (`grid --version`)
- Operating system

## 💬 Support

- 📖 **Documentation**: https://docs.grid-analyzer.com
- 💬 **Discord**: https://discord.gg/grid-analyzer
- 📧 **Email**: support@grid-analyzer.com
- 🐦 **Twitter**: [@grid_analyzer](https://twitter.com/grid_analyzer)

## 🙏 Acknowledgments

Built with:
- Local AI models (no external API calls)
- AST parsing for code analysis
- Graph visualization with D3.js
- Privacy-first architecture

---

**Made with ❤️ by the GRID Team**

[Website](https://grid-analyzer.com) • [Documentation](https://docs.grid-analyzer.com) • [Twitter](https://twitter.com/grid_analyzer)