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.

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

# 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

pip install code-pattern-search-cli

Quick Start

Basic Search

Search for a pattern in Python repositories:

code-pattern-search search "def\s+\w+" --language python

Using Presets

Use built-in preset patterns:

# 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

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:

export GITHUB_TOKEN="your_github_token_here"

Usage

Search Command

Search for code patterns in GitHub repositories:

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

# 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:

code-pattern-search cache

Clear cache:

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:

{
  "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

# 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

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.