Initial upload with CI/CD workflow

README.md

@@ -1,3 +1,286 @@
-# code-pattern-search-cli
+# Code Pattern Search CLI
 
-A CLI tool that searches GitHub repositories by actual code patterns using regex matching
+A CLI tool that searches GitHub repositories by actual code patterns using regex matching on source files. Users can search for code patterns like "React useEffect hooks", "Python dataclasses", or "Go error handling" with results ranked by repository popularity and pattern frequency.
+
+[![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/code-pattern-search-cli/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/code-pattern-search-cli/actions)
+
+## Features
+
+- **Pattern Search Command**: Search GitHub repositories using regex patterns
+- **Multi-language Regex Support**: Built-in patterns for common code patterns across languages
+- **Result Ranking**: Results ranked by repository stars and pattern frequency
+- **JSON Export**: Export search results to JSON for further analysis
+- **Caching Layer**: Cache repository file trees and API responses
+- **Preset Patterns**: Quick access to common patterns (React hooks, dataclasses, error handling, etc.)
+- **Rich Terminal Output**: Colored and formatted output using the Rich library
+
+## Installation
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/code-pattern-search-cli.git
+cd code-pattern-search-cli
+
+# Install in development mode
+pip install -e .
+
+# Or install with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Using pip
+
+```bash
+pip install code-pattern-search-cli
+```
+
+## Quick Start
+
+### Basic Search
+
+Search for a pattern in Python repositories:
+
+```bash
+code-pattern-search search "def\s+\w+" --language python
+```
+
+### Using Presets
+
+Use built-in preset patterns:
+
+```bash
+# Search for Python dataclasses
+code-pattern-search search --preset python-dataclass
+
+# Search for React useEffect hooks
+code-pattern-search search --preset react-useeffect
+
+# Search for Go error handling
+code-pattern-search search --preset go-error-handling
+```
+
+### List Available Presets
+
+```bash
+code-pattern-search presets
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `GITHUB_TOKEN` | GitHub personal access token for API rate limits | No |
+| `CPS_CACHE_DIR` | Custom cache directory path | No |
+| `CPS_CACHE_TTL` | Cache TTL in seconds (default: 3600) | No |
+
+### Setting GITHUB_TOKEN
+
+For higher API rate limits, set a GitHub personal access token:
+
+```bash
+export GITHUB_TOKEN="your_github_token_here"
+```
+
+## Usage
+
+### Search Command
+
+Search for code patterns in GitHub repositories:
+
+```bash
+code-pattern-search search [PATTERN] [OPTIONS]
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--language, -l` | Filter by programming language |
+| `--stars-min` | Minimum star count (default: 0) |
+| `--stars-max` | Maximum star count |
+| `--repos` | Number of repositories to search (default: 10) |
+| `--output, -o` | Export results to JSON file |
+| `--use-cache/--no-cache` | Use cached results (default: True) |
+| `--preset` | Use a preset pattern from the library |
+| `--verbose, -v` | Enable verbose output |
+
+### Examples
+
+```bash
+# Search for async functions in Python
+code-pattern-search search "async\s+def" --language python --stars-min 100
+
+# Search for TypeScript interfaces
+code-pattern-search search "interface\s+\w+" --language typescript
+
+# Search with star range
+code-pattern-search search "useEffect" --language javascript --stars-min 50 --stars-max 1000
+
+# Export results to JSON
+code-pattern-search search "dataclass" --output results.json
+
+# Search with verbose output
+code-pattern-search search "match\s+\w+" --language rust --verbose
+```
+
+### Cache Management
+
+View cache statistics:
+
+```bash
+code-pattern-search cache
+```
+
+Clear cache:
+
+```bash
+code-pattern-search cache --clear
+```
+
+## Pattern Library
+
+Available preset patterns organized by language:
+
+### Python
+- `python-dataclass` - Python dataclass definitions
+- `python-decorator` - Function decorators
+- `python-async` - Async function definitions
+- `python-typed-dict` - TypedDict classes
+
+### JavaScript/TypeScript
+- `react-useeffect` - React useEffect hooks
+- `react-useeffect-deps` - useEffect with dependencies
+- `js-async-await` - Async/await patterns
+- `js-fetch` - Fetch API usage
+- `ts-interface` - TypeScript interfaces
+- `ts-type-alias` - TypeScript type aliases
+- `ts-generic` - TypeScript generics
+
+### Go
+- `go-error-handling` - Error handling patterns
+- `go-defer` - Defer statements
+- `go-goroutine` - Goroutine launches
+- `go-error-wrap` - Error wrapping with fmt.Errorf
+
+### Rust
+- `rust-match` - Match expressions
+- `rust-trait` - Trait implementations
+- `rust-lifetime` - Lifetime annotations
+
+### Other
+- `docker-cmd` - Docker CMD instructions
+- `docker-entrypoint` - Docker ENTRYPOINT instructions
+- `sql-select` - SQL SELECT queries
+
+## Output Format
+
+### Terminal Output
+
+Results are displayed in a formatted table with:
+- Repository name (clickable link)
+- Star count
+- Total matches
+- Relevance score
+
+### JSON Export
+
+Exported JSON files include:
+
+```json
+{
+  "total_repositories": 5,
+  "total_matches": 42,
+  "results": [
+    {
+      "repo_name": "owner/repo",
+      "repo_url": "https://github.com/owner/repo",
+      "stars": 1000,
+      "description": "Repository description",
+      "language": "Python",
+      "matches": [
+        {
+          "file_path": "src/main.py",
+          "line_number": 42,
+          "line_content": "def hello():" ,
+          "match_start": 0,
+          "match_end": 11
+        }
+      ],
+      "total_matches": 5,
+      "score": 75.5
+    }
+  ],
+  "metadata": {
+    "exported_at": "2024-01-15T10:30:00Z",
+    "version": "0.1.0"
+  }
+}
+```
+
+## Caching
+
+The CLI uses disk-based caching with the following features:
+
+- **Persistent Cache**: Cached data survives between CLI invocations
+- **TTL-based Expiration**: Cache entries expire after configured time (default: 1 hour)
+- **Cache Keys**: Generated from hash of pattern + filters
+- **Cache Location**: Default `~/.cache/code-pattern-search/`
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v --tb=short
+
+# Run with coverage
+pytest tests/ --cov=src --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_pattern_matcher.py -v
+```
+
+### Linting
+
+```bash
+flake8 src/ tests/ --max-line-length=100
+```
+
+### Project Structure
+
+```
+code-pattern-search-cli/
+├── pyproject.toml
+├── README.md
+├── requirements.txt
+├── LICENSE
+├── .gitea/
+│   └── workflows/
+│       └── ci.yml
+├── src/
+│   ├── __init__.py
+│   ├── cli.py           # Click CLI commands
+│   ├── config.py        # Configuration management
+│   ├── github_client.py # GitHub API integration
+│   ├── pattern_matcher.py # Pattern matching engine
+│   ├── cache_manager.py  # Caching layer
+│   ├── exporter.py      # Export functionality
+│   ├── models.py        # Data models
+│   └── utils.py         # Utility functions
+└── tests/
+    ├── __init__.py
+    ├── test_cli.py
+    ├── test_pattern_matcher.py
+    ├── test_github_client.py
+    ├── test_cache_manager.py
+    └── test_exporter.py
+```
+
+## License
+
+MIT License - see LICENSE file for details.