Metadata-Version: 2.4
Name: code-guro
Version: 0.3.0
Summary: A CLI tool to help non-technical product managers and AI-native builders understand codebases
Author-email: Nicola de Vera <nicola@example.com>
License: MIT
Project-URL: Homepage, https://github.com/nicoladevera/code-guro
Project-URL: Repository, https://github.com/nicoladevera/code-guro
Project-URL: Documentation, https://github.com/nicoladevera/code-guro#readme
Project-URL: Issues, https://github.com/nicoladevera/code-guro/issues
Keywords: cli,code-analysis,documentation,learning,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.18.0
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: gitpython>=3.1
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: markdown>=3.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: enhanced
Requires-Dist: python-dotenv>=1.0; extra == "enhanced"
Requires-Dist: prompt_toolkit>=3.0; extra == "enhanced"
Requires-Dist: pygments>=2.15; extra == "enhanced"
Provides-Extra: all
Requires-Dist: code-guro[dev,enhanced]; extra == "all"

# Code Guro

A CLI tool to help non-technical product managers and AI-native builders understand codebases.

## Etymology

The name "Code Guro" is a play on two words:
- **"Guro"** - Tagalog (Filipino) word for "teacher"
- **"Guru"** - Expert or master in a particular field

This reflects the tool's purpose: to serve as both a teacher (guro) and expert guide (guru) for understanding code.

## Overview

Many product managers are now using AI coding agents (Claude Code, Cursor, etc.) to build functional prototypes and MVPs, but lack the programming background to truly understand the code that's generated. This creates hesitation when scaling products or bringing in users.

Code Guro analyzes a codebase and generates structured, beginner-friendly learning documentation. Unlike conversational AI tools that answer specific questions, Code Guro proactively creates a complete curriculum tailored to your specific codebase.

## Installation

```bash
pip3 install code-guro
```

> **Note:** On some systems, you may need to use `pip3` instead of `pip` to install Python packages.

**Requirements:**
- Python 3.8 or higher
- Internet connection (for Claude API calls)
- Claude API key from [console.anthropic.com](https://console.anthropic.com)

## Quick Start

### 1. Configure your API key

```bash
code-guro configure
```

You'll be prompted to enter your Claude API key. The key is stored securely in `~/.config/code-guro/config.json` with restricted file permissions.

Alternatively, you can set the `CLAUDE_API_KEY` or `ANTHROPIC_API_KEY` environment variable:

```bash
export CLAUDE_API_KEY="your-api-key-here"
```

### 2. Analyze a codebase

```bash
# Analyze current directory (generates both HTML and markdown)
code-guro analyze .

# Analyze a specific path
code-guro analyze /path/to/project

# Analyze from GitHub
code-guro analyze https://github.com/user/repo

# Generate only markdown (no HTML)
code-guro analyze . --markdown-only
```

### 3. Deep dive into specific files

```bash
# Explain a specific folder
code-guro explain ./src/auth

# Interactive mode for follow-up questions
code-guro explain ./src/auth --interactive

# Print explanation to console instead of file
code-guro explain ./src/auth --output console
```

## Output

By default, Code Guro generates both HTML and markdown documentation in a clean `code-guro-output/` directory:

```
code-guro-output/
├── html/
│   ├── 00-overview.html           # Executive summary: what the app does, tech stack
│   ├── 01-getting-oriented.html   # File structure, extensions glossary, entry points
│   ├── 02-architecture.html       # Patterns, conventions, architectural decisions
│   ├── 03-core-files.html         # The 20% of files that matter most
│   ├── 04-deep-dive-[module].html # Deep dives for each major module
│   ├── 05-quality-analysis.html   # What's good, what's risky, potential pitfalls
│   └── 06-next-steps.html         # Suggested exploration paths, follow-up commands
└── markdown/
    ├── 00-overview.md
    ├── 01-getting-oriented.md
    ├── 02-architecture.md
    ├── 03-core-files.md
    ├── 04-deep-dive-[module].md
    ├── 05-quality-analysis.md
    └── 06-next-steps.md
```

Each document includes:
- Beginner-friendly explanations
- Visual diagrams (Mermaid) - **fully rendered in HTML files**; markdown shows code (renders on GitHub/GitLab)
- Code snippets with inline comments
- Glossary of technical terms

**Recommended:** Open the HTML files in your browser for the best experience with fully rendered Mermaid diagrams, styling, and navigation.

### Git Integration

Since `code-guro-output/` contains generated documentation that can be recreated at any time, you may want to add it to your `.gitignore`:

```bash
echo "code-guro-output/" >> .gitignore
```

However, some users prefer to commit the documentation for:
- GitHub Pages hosting
- Team collaboration without requiring API keys
- Historical reference of code understanding

The choice is yours!

## Commands

### `code-guro configure`

Set up your Claude API key for first-time use.

```bash
code-guro configure
```

### `code-guro analyze <path>`

Analyze a codebase and generate documentation. By default, generates both HTML and markdown in organized subdirectories.

```bash
code-guro analyze .                    # Current directory (both formats)
code-guro analyze /path/to/project     # Specific path (both formats)
code-guro analyze https://github.com/user/repo  # GitHub URL (both formats)
code-guro analyze . --markdown-only    # Only markdown, no HTML
```

**Options:**
- `--markdown-only` - Generate only markdown files without HTML (default: generates both formats)

### `code-guro convert [output_dir]`

Convert existing markdown-only output to include HTML files. Useful if you previously ran analysis with `--markdown-only` and now want HTML.

```bash
code-guro convert                      # Convert from default directory (code-guro-output)
code-guro convert ./code-guro-output   # Convert from specific directory
```

This command:
- Moves markdown files into `markdown/` subdirectory
- Generates HTML files in `html/` subdirectory
- Preserves the original markdown files

### `code-guro explain <path>`

Get a detailed explanation of a specific file or folder.

```bash
code-guro explain ./src/auth           # Analyze a folder
code-guro explain ./src/app.py         # Analyze a single file
```

**Options:**
- `-i, --interactive` - Launch interactive Q&A mode
- `--output [file|console]` - Where to output (default: file)

### `code-guro --version`

Display the current version.

### `code-guro --help`

Show help information.

## Supported Frameworks

Code Guro provides enhanced context for these frameworks:

| Framework | Detection Method |
|-----------|-----------------|
| **Next.js** | `package.json` with "next", `next.config.js` |
| **React** | `package.json` with "react", `.jsx/.tsx` files |
| **Vue.js** | `package.json` with "vue", `.vue` files |
| **Django** | `requirements.txt` with "Django", `manage.py` |
| **Flask** | `requirements.txt` with "Flask", `app.py` patterns |
| **Express.js** | `package.json` with "express" |
| **Ruby on Rails** | `Gemfile` with "rails", `config/routes.rb` |

When a framework is detected, the documentation includes:
- Framework-specific architecture patterns
- Common conventions and best practices
- Known gotchas and pitfalls

## Cost Estimation

Code Guro estimates API costs before running analysis based on:
- Token count of files to analyze
- Current Claude API pricing (~$3/million input tokens, ~$15/million output tokens)

**Cost confirmation:**
- For estimates under $1.00: Proceeds automatically
- For estimates over $1.00: Asks for confirmation before continuing

Typical costs:
- Small project (10-50 files): $0.05 - $0.30
- Medium project (50-200 files): $0.30 - $1.00
- Large project (200+ files): $1.00 - $5.00

## Interactive Mode

The `--interactive` flag launches a conversational Q&A session:

```bash
code-guro explain ./src/auth --interactive
```

You can ask questions like:
- "Why was this pattern used?"
- "What does this function do?"
- "How does this connect to the database?"
- "What would happen if I changed X?"

Type `exit` or `quit` to end the session. Your conversation is saved to `code-guro-output/explain-[path]-session.md`.

## Troubleshooting

### "No API key configured"

Run `code-guro configure` to set up your API key, or set the `CLAUDE_API_KEY` environment variable.

### "No internet connection detected"

Code Guro requires an internet connection for Claude API calls and GitHub cloning. Check your network connection.

### "Estimated cost exceeds $1.00"

For large codebases, you'll be asked to confirm before proceeding. You can:
- Enter `y` to continue
- Enter `n` to cancel
- Try analyzing a specific subdirectory instead

### "File too large to analyze"

Files larger than 1MB are skipped to avoid excessive API costs. This is typically fine since large files are often generated code, dependencies, or data files.

### GitHub clone failures

Ensure the repository URL is correct and the repository is public. Private repositories are not currently supported.

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/nicoladevera/code-guro.git
cd code-guro

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage report
pytest --cov=code_guro --cov-report=term

# Generate detailed HTML coverage report
pytest --cov=code_guro --cov-report=html
# Then open htmlcov/index.html in your browser
```

**Test Coverage:** 84% (51 tests covering dual-format output, CLI commands, and generators)

All tests use mocked API calls, so they run fast and work offline without requiring API keys.

### Code Quality

**IMPORTANT**: Always run quality checks before committing to prevent CI failures:

```bash
# Recommended: Run all checks at once
make quality

# Or run individually:
black src/                # Format code
ruff check src/ --fix     # Fix linting issues
pytest                    # Run tests
```

**Pre-commit hooks** (recommended):
```bash
# Install pre-commit hooks (one-time setup)
pre-commit install

# Now checks run automatically before each commit
# To run manually on all files:
pre-commit run --all-files
```

The pre-commit hooks will:
- Auto-format code with Black (100 char line length)
- Auto-fix import sorting and remove unused imports
- Run Ruff linter with auto-fix
- Prevent commits if issues remain

## License

MIT

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, code style, and the release process.

## Acknowledgments

Built with:
- [Anthropic Claude API](https://www.anthropic.com/)
- [Click](https://click.palletsprojects.com/) - CLI framework
- [Rich](https://rich.readthedocs.io/) - Terminal formatting
- [tiktoken](https://github.com/openai/tiktoken) - Token counting
