code-pattern-search-cli/README.md

Code Pattern Search CLI

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.