codesnap/README.md

CodeSnap - Codebase Summarization CLI

A CLI tool that analyzes codebases and generates concise, human-readable summaries including file structure, key functions/classes, dependencies, and architectural patterns. Useful for onboarding, understanding legacy code, and providing context to AI assistants.

Features

• Multi-language Support: Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, Ruby, PHP
• Dependency Analysis: Build import/dependency graphs using NetworkX
• Complexity Scoring: Calculate cyclomatic complexity with ratings (low/medium/high/critical)
• Multiple Output Formats: JSON, Markdown, and LLM-optimized output
• Tree-sitter Parsing: Accurate code parsing for extraction
• Configuration: YAML-based configuration with environment variable overrides

Installation

From PyPI (Recommended)

pip install codesnap

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/codesnap.git
cd codesnap
pip install -e .

Development Installation

pip install -e ".[dev]"

Usage

Basic Analysis

Analyze a directory and generate a summary:

codesnap analyze /path/to/project

Output Formats

Markdown (Default)

codesnap analyze /path/to/project --output markdown

Generates a human-readable report with:

• Language breakdown
• File structure (tree view)
• Key functions and classes
• Dependencies
• Complexity metrics

JSON

codesnap analyze /path/to/project --output json

Generates structured JSON output suitable for programmatic processing.

LLM-Optimized

codesnap analyze /path/to/project --output llm --max-tokens 4000

Optimized output for AI assistants with token limiting.

Dependency Analysis

Show dependency graph for a codebase:

codesnap deps /path/to/project

Shows:

• Graph statistics
• Circular dependencies
• Most depended-on files
• Most dependent files

Complexity Analysis

Calculate complexity metrics:

codesnap complexity /path/to/project

Shows complexity ratings (low/medium/high/critical) for each file.

List Supported Languages

codesnap languages

Shows all supported programming languages and file extensions.

Configuration

Create a .codesnaprc file in your project root:

max_files: 1000
max_tokens: 8000

include_patterns:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"

exclude_patterns:
  - "**/node_modules/**"
  - "**/.git/**"
  - "**/venv/**"

complexity:
  low: 10
  medium: 20
  high: 50

Environment Variables

Variable	Description	Default
CODSNAP_MAX_FILES	Maximum files to analyze	1000
CODSNAP_MAX_TOKENS	Maximum output tokens	8000
CODSNAP_GRCACHE	Tree-sitter grammar cache	~/.cache/codesnap/grammars

Output Formats

JSON Schema

{
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "0.1.0",
  "directory": "/path/to/project",
  "file_count": 10,
  "language_breakdown": {
    "python": 5,
    "javascript": 3,
    "typescript": 2
  },
  "files": [
    {
      "path": "/path/to/project/main.py",
      "language": "python",
      "functions": [...],
      "classes": [...]
    }
  ],
  "dependencies": {
    "main.py": ["utils.py", "config.py"]
  },
  "metrics": {
    "total_functions": 25,
    "total_classes": 5,
    "cycles_found": 0
  }
}

Examples

Analyze a Python Project

codesnap analyze ./my-python-app --output markdown

Analyze with Token Limit for LLM

codesnap analyze ./large-project --output llm --max-tokens 4000 > summary.txt

Find Circular Dependencies

codesnap deps ./project

Quick Complexity Check

codesnap complexity ./project --format markdown

Supported Languages

• Python (.py, .pyw, .pyi)
• JavaScript (.js, .mjs, .cjs)
• TypeScript (.ts, .tsx)
• Go (.go)
• Rust (.rs)
• Java (.java)
• C/C++ (.c, .cpp, .cc, .h, .hpp)
• Ruby (.rb)
• PHP (.php)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.