Initial upload with CI/CD workflow

2026-01-30 22:12:47 +00:00
parent 62a24e04fa
commit be561b8a36
1 changed files with 222 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,223 @@
-# codesnap
+# 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.
+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)
+
+```bash
+pip install codesnap
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/codesnap.git
+cd codesnap
+pip install -e .
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Basic Analysis
+
+Analyze a directory and generate a summary:
+
+```bash
+codesnap analyze /path/to/project
+```
+
+### Output Formats
+
+#### Markdown (Default)
+
+```bash
+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
+
+```bash
+codesnap analyze /path/to/project --output json
+```
+
+Generates structured JSON output suitable for programmatic processing.
+
+#### LLM-Optimized
+
+```bash
+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:
+
+```bash
+codesnap deps /path/to/project
+```
+
+Shows:
+- Graph statistics
+- Circular dependencies
+- Most depended-on files
+- Most dependent files
+
+### Complexity Analysis
+
+Calculate complexity metrics:
+
+```bash
+codesnap complexity /path/to/project
+```
+
+Shows complexity ratings (low/medium/high/critical) for each file.
+
+### List Supported Languages
+
+```bash
+codesnap languages
+```
+
+Shows all supported programming languages and file extensions.
+
+## Configuration
+
+Create a `.codesnaprc` file in your project root:
+
+```yaml
+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
+
+```json
+{
+  "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
+
+```bash
+codesnap analyze ./my-python-app --output markdown
+```
+
+### Analyze with Token Limit for LLM
+
+```bash
+codesnap analyze ./large-project --output llm --max-tokens 4000 > summary.txt
+```
+
+### Find Circular Dependencies
+
+```bash
+codesnap deps ./project
+```
+
+### Quick Complexity Check
+
+```bash
+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.