docs: create comprehensive documentation and banner
- Add comprehensive documentation suite in docs/ directory - ARCHITECTURE.md: System design and technical architecture - CONTRIBUTING.md: Development guidelines and contribution process - installation.md: Detailed installation instructions - usage.md: Command-line options and game interface guide - supported-languages.md: Language support status and roadmap - docs/images/README.md: Banner generation instructions - Create professional banner image with GitType ASCII logo - Generate 1200x630px OGP-compliant PNG banner - Include SVG version for scalability - Use Ubuntu Mono font with proper spacing and readability - Add shell script for banner regeneration - Update main README.md with modern design - Add banner image at top - Restructure content with better sections and emojis - Add catchphrase: "Show your AI who's boss: just you, your keyboard, and your coding sins" - Include comprehensive "Why GitType?" section with humor - Link to all documentation files - Add MIT LICENSE file - Update language support roadmap - Prioritize Swift, Kotlin, Ruby as high priority - Add more languages with realistic timelines 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Yuji Ueki
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025 unhappychoice
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -1,81 +1,74 @@
|
||||
# GitType
|
||||
|
||||
|
||||
**GitType** is a CLI typing game that turns your source code into typing challenges.
|
||||
Instead of random text or docs, you practice by typing actual functions and classes from your repository.
|
||||
# GitType ⌨️💻
|
||||
|
||||
---
|
||||
> *"Show your AI who's boss: just you, your keyboard, and your coding sins"*
|
||||
|
||||
## Concept
|
||||
**GitType** turns your own source code into typing challenges. Because why practice with boring lorem ipsum when you can type your beautiful `fn main()` implementations?
|
||||
|
||||
- **Type your source**: Extract functions, classes, and code blocks from your repo and turn them into typing challenges.
|
||||
- **Practical training**: Practice with real syntax, keywords, and identifiers.
|
||||
- **Fun alternative to 写経**: Typing code feels less like copying work and more like a game.
|
||||
## Features ✨
|
||||
|
||||
---
|
||||
- 🌳 **Tree-sitter powered**: Extracts actual functions, not random code snippets
|
||||
- 🦀🐍⚡ **Multi-language**: Rust, TypeScript, Python (more languages incoming!)
|
||||
- 📊 **Git stats vibes**: Track your WPM like you track your commit frequency
|
||||
- 🎯 **Actually useful**: Build muscle memory with *real* syntax patterns
|
||||
- 🔍 **Smart filtering**: Skip the `node_modules` nightmare automatically
|
||||
|
||||
## Features (Planned)
|
||||
|
||||
- Extract **functions and classes** (via [tree-sitter](https://tree-sitter.github.io/tree-sitter/))
|
||||
- Adjustable chunk size (e.g., max 40 lines per challenge)
|
||||
- Scoring system:
|
||||
- Accuracy (%)
|
||||
- Speed (WPM)
|
||||
- Mistakes per challenge
|
||||
- **Local history**: track your past scores, mistakes, and progress
|
||||
- **Online ranking (optional)**: compete with other developers on shared leaderboards
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
## Quick Start 🚀
|
||||
|
||||
```bash
|
||||
gittype [path/to/repo] [options]
|
||||
# Install (yes, it's that easy)
|
||||
brew install gittype
|
||||
|
||||
# cd into your messy codebase
|
||||
cd ~/that-project-you-never-finished
|
||||
|
||||
# Start typing your own spaghetti code
|
||||
gittype
|
||||
```
|
||||
|
||||
### Options
|
||||
## Demo 🎮
|
||||
|
||||
```text
|
||||
--langs ts,rs,py Filter by language
|
||||
--unit function,class Extraction unit
|
||||
--max-lines 40 Max lines per challenge
|
||||
--include "src/**" Glob include filter
|
||||
--exclude "node_modules/**" Glob exclude filter
|
||||
```rust
|
||||
[src/main.rs:42-58] (Rust function)
|
||||
// ^ This could be YOUR code!
|
||||
|
||||
fn debug_everything(life: &str) -> Result<(), PanicMode> {
|
||||
println!("It works on my machine: {}", life);
|
||||
todo!("fix this before prod")
|
||||
}
|
||||
> _
|
||||
```
|
||||
|
||||
*Type it exactly as shown. Yes, including that `todo!()` you left 6 months ago.*
|
||||
|
||||
## Why GitType? 🤔
|
||||
|
||||
- **Look busy at work** → "I'm studying the codebase" (technically true!)
|
||||
- **Beat the AI overlords** → Type faster than ChatGPT can generate
|
||||
- **Stop typing boring stuff** → Your own bugs are way more interesting than lorem ipsum
|
||||
- **Discover forgotten treasures** → That elegant function you wrote at 3am last year
|
||||
- **Procrastinate like a pro** → It's code review, but gamified!
|
||||
- **Embrace your legacy code** → Finally face those variable names you're not proud of
|
||||
- **Debug your typing skills** → Because `pubic static void main` isn't a typo anymore
|
||||
- **Therapeutic code reliving** → Type through your programming journey, tears included
|
||||
|
||||
*"Basically, you need an excuse to avoid real work, and this one's pretty good."*
|
||||
|
||||
## Documentation 📚
|
||||
|
||||
Perfect for when the game gets too addictive:
|
||||
|
||||
- **[Installation](docs/installation.md)** - `cargo install` and chill
|
||||
- **[Usage](docs/usage.md)** - All the CLI flags your heart desires
|
||||
- **[Languages](docs/supported-languages.md)** - What we extract and how
|
||||
- **[Contributing](docs/CONTRIBUTING.md)** - Join the keyboard warriors
|
||||
- **[Architecture](docs/ARCHITECTURE.md)** - For the curious minds
|
||||
|
||||
## License 📄
|
||||
|
||||
[MIT](LICENSE) - Because sharing is caring (and legal requirements)
|
||||
|
||||
---
|
||||
|
||||
## Example Challenge
|
||||
|
||||
```text
|
||||
[src/lib.rs:42-68] (Rust function)
|
||||
|
||||
fn calculate_metrics(deps: &Dependencies) -> MetricsResult {
|
||||
>
|
||||
```
|
||||
|
||||
You type until the snippet is complete. Score is calculated from accuracy and speed. Mistakes are logged for review.
|
||||
|
||||
---
|
||||
|
||||
## Why?
|
||||
|
||||
Typing practice with **real code** builds fluency with actual syntax and project vocabulary.
|
||||
It turns repetition into **productive fun** while helping you notice details in codebases.
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
```text
|
||||
[ ] Source extraction (functions/classes)
|
||||
[ ] Local scoring + history
|
||||
[ ] Local analytics (mistakes, accuracy trends)
|
||||
[ ] Online ranking / leaderboard
|
||||
[ ] Multi-language support (Rust, TypeScript, Python, etc.)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
*Built with ❤️ and way too much caffeine by developers who got tired of typing "hello world"*
|
||||
|
||||
@@ -0,0 +1,429 @@
|
||||
# GitType Architecture
|
||||
|
||||
This document describes the overall architecture and design decisions of GitType, a CLI typing game that uses source code as practice material.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Architecture Patterns](#architecture-patterns)
|
||||
- [Core Modules](#core-modules)
|
||||
- [Data Flow](#data-flow)
|
||||
- [Key Components](#key-components)
|
||||
- [External Dependencies](#external-dependencies)
|
||||
- [Design Decisions](#design-decisions)
|
||||
- [Performance Considerations](#performance-considerations)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
GitType follows a modular architecture with clear separation of concerns:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CLI │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Game Engine │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Extractor │ Scoring │ Storage │ Sharing │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ External Dependencies (tree-sitter, etc.) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Modularity**: Each component has a single responsibility
|
||||
- **Testability**: Components are easily unit tested in isolation
|
||||
- **Performance**: Async processing and parallel parsing where beneficial
|
||||
- **Extensibility**: Easy to add new languages and features
|
||||
- **User Experience**: Responsive UI with real-time feedback
|
||||
|
||||
---
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Module Pattern
|
||||
Each major feature area is organized as a separate module with clear public APIs:
|
||||
- `extractor`: Code extraction and parsing
|
||||
- `game`: Game mechanics and UI
|
||||
- `scoring`: Performance metrics and calculation
|
||||
- `storage`: Data persistence and history
|
||||
- `cli`: Command-line interface and configuration
|
||||
|
||||
### Repository Pattern
|
||||
The `RepositoryLoader` abstracts file system access, making it easy to:
|
||||
- Test with mock data
|
||||
- Support different source types (local files, git repos)
|
||||
- Add filtering and preprocessing
|
||||
|
||||
### Strategy Pattern
|
||||
Language-specific extraction is handled through the `Language` enum and associated parsing strategies, allowing easy extension for new programming languages.
|
||||
|
||||
---
|
||||
|
||||
## Core Modules
|
||||
|
||||
### 1. CLI Module (`src/cli/`)
|
||||
|
||||
**Purpose**: Command-line interface and configuration management
|
||||
|
||||
```rust
|
||||
pub struct Config {
|
||||
pub repo_path: PathBuf,
|
||||
pub languages: Vec<Language>,
|
||||
pub max_lines: usize,
|
||||
pub stages: usize,
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Key Components**:
|
||||
- `config.rs`: Configuration parsing and validation
|
||||
- Command-line argument parsing with `clap`
|
||||
- Configuration file support
|
||||
|
||||
### 2. Extractor Module (`src/extractor/`)
|
||||
|
||||
**Purpose**: Extract code chunks from source repositories
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
RepositoryLoader -> Parser -> CodeChunk -> ChallengeConverter
|
||||
```
|
||||
|
||||
**Key Components**:
|
||||
- `repository_loader.rs`: File discovery and filtering
|
||||
- `parser.rs`: Tree-sitter based code parsing
|
||||
- `chunk.rs`: Code chunk representation and metadata
|
||||
- `language.rs`: Language detection and configuration
|
||||
- `challenge_converter.rs`: Convert chunks to typing challenges
|
||||
|
||||
**Data Flow**:
|
||||
1. `RepositoryLoader` discovers and filters files
|
||||
2. `CodeExtractor` parses files using tree-sitter
|
||||
3. `CodeChunk` objects are created with metadata
|
||||
4. `ChallengeConverter` transforms chunks into typing challenges
|
||||
|
||||
### 3. Game Module (`src/game/`)
|
||||
|
||||
**Purpose**: Game mechanics, UI, and user interaction
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
StageManager -> Screen -> Display -> User Input
|
||||
↓
|
||||
SessionTracker -> Scoring -> Storage
|
||||
```
|
||||
|
||||
**Key Components**:
|
||||
- `stage_manager.rs`: Orchestrates game flow and state
|
||||
- `screens/`: Different UI screens (title, typing, results, etc.)
|
||||
- `display.rs`: Terminal UI rendering with ratatui
|
||||
- `challenge.rs`: Individual typing challenge logic
|
||||
- `session_tracker.rs`: Track user progress through sessions
|
||||
|
||||
**Screen Flow**:
|
||||
```
|
||||
TitleScreen -> LoadingScreen -> CountdownScreen -> TypingScreen -> ResultScreen
|
||||
↑__________________|
|
||||
```
|
||||
|
||||
### 4. Scoring Module (`src/scoring/`)
|
||||
|
||||
**Purpose**: Calculate performance metrics
|
||||
|
||||
```rust
|
||||
pub struct TypingMetrics {
|
||||
pub accuracy: f64,
|
||||
pub words_per_minute: f64,
|
||||
pub characters_per_minute: f64,
|
||||
pub mistakes: usize,
|
||||
pub total_time: Duration,
|
||||
}
|
||||
```
|
||||
|
||||
**Key Components**:
|
||||
- `engine.rs`: Real-time scoring calculation
|
||||
- `metrics.rs`: Performance metric definitions
|
||||
- `ranking_title.rs`: Rank calculation and titles
|
||||
|
||||
### 5. Storage Module (`src/storage/`)
|
||||
|
||||
**Purpose**: Data persistence and session history
|
||||
|
||||
**Components**:
|
||||
- `database.rs`: SQLite database management
|
||||
- `history.rs`: Session history and statistics
|
||||
- Local storage for user progress and analytics
|
||||
|
||||
### 6. Sharing Module (`src/sharing.rs`)
|
||||
|
||||
**Purpose**: Share results and statistics
|
||||
|
||||
**Features**:
|
||||
- Export session data
|
||||
- Generate shareable statistics
|
||||
- Integration with external services (planned)
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### 1. Initialization Flow
|
||||
|
||||
```
|
||||
CLI Args -> Config -> RepositoryLoader -> CodeExtractor
|
||||
↓
|
||||
FileDiscovery -> TreeSitter -> CodeChunks
|
||||
↓
|
||||
ChallengeConverter -> GameChallenges
|
||||
```
|
||||
|
||||
### 2. Game Loop Flow
|
||||
|
||||
```
|
||||
User Input -> TypingScreen -> ScoringEngine -> RealTimeMetrics
|
||||
↓ ↓ ↓
|
||||
StageManager -> SessionTracker -> Database
|
||||
↓
|
||||
ResultScreen -> NextChallenge/GameEnd
|
||||
```
|
||||
|
||||
### 3. Storage Flow
|
||||
|
||||
```
|
||||
SessionData -> Database -> History -> Analytics
|
||||
↓
|
||||
Export -> JSON/CSV
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Components
|
||||
|
||||
### CodeChunk
|
||||
|
||||
Represents a piece of extracted code with metadata:
|
||||
|
||||
```rust
|
||||
pub struct CodeChunk {
|
||||
pub content: String,
|
||||
pub chunk_type: ChunkType,
|
||||
pub file_path: PathBuf,
|
||||
pub start_line: usize,
|
||||
pub end_line: usize,
|
||||
pub language: Language,
|
||||
}
|
||||
|
||||
pub enum ChunkType {
|
||||
Function,
|
||||
Class,
|
||||
Method,
|
||||
Struct,
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Challenge
|
||||
|
||||
Represents a typing challenge created from a code chunk:
|
||||
|
||||
```rust
|
||||
pub struct Challenge {
|
||||
pub id: String,
|
||||
pub content: String,
|
||||
pub source_info: SourceInfo,
|
||||
pub difficulty: DifficultyLevel,
|
||||
}
|
||||
```
|
||||
|
||||
### StageManager
|
||||
|
||||
Orchestrates the game flow and manages state transitions:
|
||||
|
||||
```rust
|
||||
pub struct StageManager {
|
||||
pub current_stage: usize,
|
||||
pub challenges: Vec<Challenge>,
|
||||
pub session_tracker: SessionTracker,
|
||||
pub stage_config: StageConfig,
|
||||
}
|
||||
```
|
||||
|
||||
### Display System
|
||||
|
||||
Multi-layered rendering system:
|
||||
- `display.rs`: Abstract display interface
|
||||
- `display_ratatui.rs`: Terminal UI implementation
|
||||
- `display_optimized.rs`: Performance-optimized rendering
|
||||
|
||||
---
|
||||
|
||||
## External Dependencies
|
||||
|
||||
### Core Dependencies
|
||||
|
||||
| Dependency | Purpose | Usage |
|
||||
|------------|---------|-------|
|
||||
| `tree-sitter` | Code parsing | Extract functions, classes from source files |
|
||||
| `ratatui` | Terminal UI | Render game interface |
|
||||
| `crossterm` | Terminal control | Handle input, colors, cursor positioning |
|
||||
| `clap` | CLI parsing | Command-line argument handling |
|
||||
| `rusqlite` | Database | Store session history and statistics |
|
||||
| `rayon` | Parallelism | Parallel file processing |
|
||||
|
||||
### Language-Specific
|
||||
|
||||
| Language | Tree-sitter Grammar | Status |
|
||||
|----------|-------------------|---------|
|
||||
| Rust | `tree-sitter-rust` | ✅ Full support |
|
||||
| TypeScript | `tree-sitter-typescript` | ✅ Full support |
|
||||
| Python | `tree-sitter-python` | ✅ Full support |
|
||||
|
||||
---
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### 1. Tree-sitter for Code Parsing
|
||||
|
||||
**Why**: Provides accurate, language-aware parsing that understands code structure rather than just text patterns.
|
||||
|
||||
**Benefits**:
|
||||
- Consistent extraction across languages
|
||||
- Accurate function/class boundaries
|
||||
- Syntax highlighting support
|
||||
- Extensible to new languages
|
||||
|
||||
### 2. Terminal UI with Ratatui
|
||||
|
||||
**Why**: Provides rich, responsive terminal interface without requiring GUI dependencies.
|
||||
|
||||
**Benefits**:
|
||||
- Cross-platform compatibility
|
||||
- Low resource usage
|
||||
- Professional appearance
|
||||
- Real-time updates
|
||||
|
||||
### 3. SQLite for Storage
|
||||
|
||||
**Why**: Local, file-based database that requires no setup.
|
||||
|
||||
**Benefits**:
|
||||
- No external database server needed
|
||||
- ACID transactions
|
||||
- SQL query capabilities
|
||||
- Portable data files
|
||||
|
||||
### 4. Modular Architecture
|
||||
|
||||
**Why**: Separation of concerns makes the codebase maintainable and testable.
|
||||
|
||||
**Benefits**:
|
||||
- Easy to add new features
|
||||
- Component-level testing
|
||||
- Clear interfaces
|
||||
- Parallel development
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Parallel Processing
|
||||
|
||||
```rust
|
||||
// Parallel file processing with rayon
|
||||
files.par_iter()
|
||||
.map(|file| extract_chunks(file))
|
||||
.collect()
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- Faster repository scanning
|
||||
- Efficient multi-core usage
|
||||
- Better user experience for large codebases
|
||||
|
||||
### 2. Lazy Loading
|
||||
|
||||
- Code chunks are processed on-demand
|
||||
- UI screens are rendered only when needed
|
||||
- Database connections are managed efficiently
|
||||
|
||||
### 3. Memory Management
|
||||
|
||||
- Streaming file processing for large repositories
|
||||
- Efficient string handling for code content
|
||||
- Bounded memory usage regardless of repository size
|
||||
|
||||
### 4. Caching Strategy
|
||||
|
||||
- Parsed code chunks can be cached between sessions
|
||||
- Git repository metadata is cached
|
||||
- Display rendering optimizations
|
||||
|
||||
---
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Adding New Languages
|
||||
|
||||
1. Add tree-sitter grammar dependency
|
||||
2. Implement language-specific queries
|
||||
3. Update `Language` enum
|
||||
4. Add language detection logic
|
||||
5. Include tests and documentation
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. **Game Modes**: Extend `GameMode` enum and `StageBuilder`
|
||||
2. **Scoring Systems**: Add new metrics to `ScoringEngine`
|
||||
3. **Display Options**: Implement new `Display` trait variants
|
||||
4. **Export Formats**: Extend `sharing` module
|
||||
|
||||
### Adding New Screens
|
||||
|
||||
1. Implement `Screen` trait
|
||||
2. Add to `screens` module
|
||||
3. Update `StageManager` flow
|
||||
4. Add navigation logic
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- Each module has comprehensive unit tests
|
||||
- Mock dependencies for isolated testing
|
||||
- Property-based testing for parsers
|
||||
|
||||
### Integration Tests
|
||||
- End-to-end CLI testing
|
||||
- Database integration tests
|
||||
- Multi-language extraction tests
|
||||
|
||||
### Performance Tests
|
||||
- Benchmarks for parsing large codebases
|
||||
- Memory usage profiling
|
||||
- UI responsiveness testing
|
||||
|
||||
---
|
||||
|
||||
## Future Architecture Considerations
|
||||
|
||||
### Planned Improvements
|
||||
|
||||
1. **Plugin System**: Allow external language support
|
||||
2. **Remote Storage**: Cloud-based session synchronization
|
||||
3. **Multi-Player**: Real-time competitive typing
|
||||
4. **Analytics**: Advanced performance insights
|
||||
5. **Web Interface**: Browser-based version
|
||||
|
||||
### Scalability
|
||||
|
||||
- Modular design supports horizontal feature additions
|
||||
- Clear interfaces enable component replacement
|
||||
- Performance optimizations can be added incrementally
|
||||
|
||||
---
|
||||
|
||||
This architecture provides a solid foundation for GitType's current features while maintaining flexibility for future enhancements.
|
||||
@@ -0,0 +1,342 @@
|
||||
# Contributing to GitType
|
||||
|
||||
Thank you for your interest in contributing to GitType! This document provides guidelines and information for contributors.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Making Changes](#making-changes)
|
||||
- [Testing](#testing)
|
||||
- [Submitting Changes](#submitting-changes)
|
||||
- [Coding Standards](#coding-standards)
|
||||
- [Adding Language Support](#adding-language-support)
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
This project follows a standard code of conduct. Please be respectful and constructive in all interactions.
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Rust 1.70 or later
|
||||
- Git
|
||||
- Basic familiarity with Rust and CLI development
|
||||
|
||||
### Development Setup
|
||||
|
||||
1. **Fork and clone the repository:**
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/gittype.git
|
||||
cd gittype
|
||||
```
|
||||
|
||||
2. **Set up the development environment:**
|
||||
```bash
|
||||
# Install dependencies and build
|
||||
cargo build
|
||||
|
||||
# Run tests to ensure everything works
|
||||
cargo test
|
||||
|
||||
# Try running the application
|
||||
cargo run -- --help
|
||||
```
|
||||
|
||||
3. **Create a development branch:**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
gittype/
|
||||
├── src/
|
||||
│ ├── main.rs # CLI entry point
|
||||
│ ├── lib.rs # Library root
|
||||
│ ├── extractor/ # Code extraction logic
|
||||
│ │ ├── mod.rs # Main extractor interface
|
||||
│ │ ├── repository.rs # Repository loading
|
||||
│ │ └── languages/ # Language-specific parsers
|
||||
│ ├── game/ # Game logic and UI
|
||||
│ │ ├── mod.rs # Game orchestration
|
||||
│ │ ├── stage_manager.rs # Stage management
|
||||
│ │ ├── scoring/ # Scoring system
|
||||
│ │ └── screens/ # UI screens
|
||||
│ └── database/ # Session storage
|
||||
├── tests/ # Integration tests
|
||||
├── Cargo.toml # Project configuration
|
||||
└── README.md # Project documentation
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
- **Extractor**: Handles parsing source code using tree-sitter
|
||||
- **Game**: Manages typing challenges and user interface
|
||||
- **Database**: Stores session history and statistics
|
||||
- **Scoring**: Calculates accuracy, speed, and other metrics
|
||||
|
||||
---
|
||||
|
||||
## Making Changes
|
||||
|
||||
### Types of Contributions
|
||||
|
||||
1. **Bug Fixes**: Fix issues in existing functionality
|
||||
2. **Features**: Add new functionality or improve existing features
|
||||
3. **Performance**: Optimize code performance
|
||||
4. **Documentation**: Improve or add documentation
|
||||
5. **Language Support**: Add support for new programming languages
|
||||
|
||||
### Before You Start
|
||||
|
||||
1. Check existing issues and PRs to avoid duplication
|
||||
2. For major features, consider opening an issue first to discuss
|
||||
3. Ensure your changes align with the project goals
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
cargo test
|
||||
|
||||
# Run with output
|
||||
cargo test -- --nocapture
|
||||
|
||||
# Run specific test
|
||||
cargo test test_name
|
||||
|
||||
# Run integration tests
|
||||
cargo test --test integration_tests
|
||||
```
|
||||
|
||||
### Test Coverage
|
||||
|
||||
- Unit tests for core logic components
|
||||
- Integration tests for CLI functionality
|
||||
- Test files in various languages for extractor testing
|
||||
|
||||
### Writing Tests
|
||||
|
||||
- Add unit tests for new functions
|
||||
- Include integration tests for CLI features
|
||||
- Test edge cases and error conditions
|
||||
- Use descriptive test names
|
||||
|
||||
Example:
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_extract_rust_functions() {
|
||||
let code = r#"
|
||||
fn example_function() {
|
||||
println!("Hello, world!");
|
||||
}
|
||||
"#;
|
||||
|
||||
let extractor = RustExtractor::new();
|
||||
let chunks = extractor.extract(code).unwrap();
|
||||
|
||||
assert_eq!(chunks.len(), 1);
|
||||
assert_eq!(chunks[0].function_name(), "example_function");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Submitting Changes
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. **Ensure your branch is up to date:**
|
||||
```bash
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
git checkout your-branch
|
||||
git rebase main
|
||||
```
|
||||
|
||||
2. **Run the full test suite:**
|
||||
```bash
|
||||
cargo test
|
||||
cargo clippy -- -D warnings
|
||||
cargo fmt -- --check
|
||||
```
|
||||
|
||||
3. **Commit your changes:**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "type: description of changes"
|
||||
```
|
||||
|
||||
4. **Push to your fork:**
|
||||
```bash
|
||||
git push origin your-branch
|
||||
```
|
||||
|
||||
5. **Create a pull request:**
|
||||
- Use a descriptive title
|
||||
- Explain what changes were made and why
|
||||
- Reference any related issues
|
||||
- Include screenshots for UI changes
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
Use conventional commit format:
|
||||
|
||||
```
|
||||
type(scope): description
|
||||
|
||||
body (optional)
|
||||
|
||||
footer (optional)
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes (formatting, etc.)
|
||||
- `refactor`: Code refactoring
|
||||
- `perf`: Performance improvements
|
||||
- `test`: Adding or updating tests
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
Examples:
|
||||
- `feat: add support for Go language extraction`
|
||||
- `fix: handle empty files in extractor`
|
||||
- `docs: update installation instructions`
|
||||
|
||||
---
|
||||
|
||||
## Coding Standards
|
||||
|
||||
### Rust Style
|
||||
|
||||
- Follow the [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/)
|
||||
- Use `rustfmt` for formatting: `cargo fmt`
|
||||
- Use `clippy` for linting: `cargo clippy`
|
||||
- Write descriptive variable and function names
|
||||
- Add documentation comments for public APIs
|
||||
|
||||
### Code Quality
|
||||
|
||||
- Keep functions focused and reasonably sized
|
||||
- Use meaningful error types and messages
|
||||
- Handle all error cases appropriately
|
||||
- Avoid unwrap() in production code - use proper error handling
|
||||
- Write self-documenting code with good naming
|
||||
|
||||
### Example Code Style
|
||||
|
||||
```rust
|
||||
/// Extracts code chunks from a source file
|
||||
pub fn extract_chunks(
|
||||
file_path: &Path,
|
||||
language: Language,
|
||||
max_lines: usize,
|
||||
) -> Result<Vec<CodeChunk>, ExtractionError> {
|
||||
let content = std::fs::read_to_string(file_path)
|
||||
.map_err(|e| ExtractionError::FileRead(e))?;
|
||||
|
||||
let parser = create_parser(language)?;
|
||||
let tree = parser.parse(&content, None)
|
||||
.ok_or(ExtractionError::ParseFailed)?;
|
||||
|
||||
extract_from_tree(&tree, &content, max_lines)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding Language Support
|
||||
|
||||
### Steps to Add a New Language
|
||||
|
||||
1. **Add the tree-sitter dependency:**
|
||||
```toml
|
||||
# In Cargo.toml
|
||||
tree-sitter-newlang = "0.20"
|
||||
```
|
||||
|
||||
2. **Create language-specific extractor:**
|
||||
```rust
|
||||
// src/extractor/languages/newlang.rs
|
||||
use tree_sitter::Language;
|
||||
|
||||
extern "C" {
|
||||
fn tree_sitter_newlang() -> Language;
|
||||
}
|
||||
|
||||
pub fn language() -> Language {
|
||||
unsafe { tree_sitter_newlang() }
|
||||
}
|
||||
|
||||
pub const QUERY: &str = r#"
|
||||
(function_definition
|
||||
name: (identifier) @function.name) @function.definition
|
||||
"#;
|
||||
```
|
||||
|
||||
3. **Update the main extractor:**
|
||||
```rust
|
||||
// src/extractor/mod.rs
|
||||
match language {
|
||||
Language::NewLang => languages::newlang::create_extractor(),
|
||||
// ... other languages
|
||||
}
|
||||
```
|
||||
|
||||
4. **Add tests:**
|
||||
```rust
|
||||
#[test]
|
||||
fn test_newlang_extraction() {
|
||||
// Test with sample code
|
||||
}
|
||||
```
|
||||
|
||||
5. **Update documentation:**
|
||||
- Add to supported languages list in README.md
|
||||
- Include examples if needed
|
||||
|
||||
### Query Writing Guidelines
|
||||
|
||||
- Focus on extracting meaningful code units (functions, classes, methods)
|
||||
- Ensure extracted chunks are self-contained
|
||||
- Test queries with various code samples
|
||||
- Consider edge cases and complex syntax
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Issues**: Browse existing issues or create a new one
|
||||
- **Discussions**: Use GitHub Discussions for questions
|
||||
- **Documentation**: Check the README and code comments
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors will be acknowledged in:
|
||||
- CONTRIBUTORS.md file
|
||||
- Release notes for significant contributions
|
||||
- Repository insights and statistics
|
||||
|
||||
Thank you for contributing to GitType! 🚀
|
||||
@@ -0,0 +1,62 @@
|
||||
# GitType Banner Images
|
||||
|
||||
This directory contains the banner images used in the project.
|
||||
|
||||
## Files
|
||||
|
||||
- `gittype-banner.png` - Main banner image (1200x630px, OGP-ready)
|
||||
- `gittype-banner.svg` - Vector version of the banner
|
||||
- `banner-source.sh` - Shell script that generates the banner content
|
||||
|
||||
## Regenerating the Banner
|
||||
|
||||
To regenerate the banner images, use the following commands:
|
||||
|
||||
### Dependencies
|
||||
```bash
|
||||
npm install -g oh-my-logo
|
||||
go install github.com/charmbracelet/freeze@latest
|
||||
```
|
||||
|
||||
### PNG Banner (1200x630px - OGP ready)
|
||||
```bash
|
||||
freeze --execute "docs/images/banner-source.sh" \
|
||||
-o docs/images/gittype-banner.png \
|
||||
--theme "Dracula" \
|
||||
--window \
|
||||
--background="#1e1e2e" \
|
||||
--margin 10 \
|
||||
--padding 40 \
|
||||
--border.radius 15 \
|
||||
--font.family "Ubuntu Mono" \
|
||||
--font.size 22 \
|
||||
--width 1200 \
|
||||
--height 630
|
||||
```
|
||||
|
||||
### SVG Banner
|
||||
```bash
|
||||
freeze --execute "docs/images/banner-source.sh" \
|
||||
-o docs/images/gittype-banner.svg \
|
||||
--theme "Dracula" \
|
||||
--window \
|
||||
--background="#1e1e2e" \
|
||||
--margin 10 \
|
||||
--padding 40 \
|
||||
--border.radius 15 \
|
||||
--font.family "Ubuntu Mono" \
|
||||
--font.size 22 \
|
||||
--width 1200 \
|
||||
--height 630
|
||||
```
|
||||
|
||||
## Banner Design
|
||||
|
||||
The banner features:
|
||||
- GitType ASCII logo with purple gradient generated by `oh-my-logo`
|
||||
- Project tagline: "Show your AI who's boss: just you, your keyboard, and your coding sins"
|
||||
- Feature highlights with ASCII icons: [*] Addictive gameplay [>] Real-time feedback [+] Track your progress
|
||||
- Installation commands for brew and usage
|
||||
- GitHub repository URL
|
||||
- Terminal-style appearance with window controls and dark Dracula theme background
|
||||
- Ubuntu Mono font for optimal readability and emoji compatibility
|
||||
Executable
+25
@@ -0,0 +1,25 @@
|
||||
#!/bin/bash
|
||||
# GitType Banner Generator Script
|
||||
# This script generates the GitType banner image using freeze
|
||||
|
||||
export FORCE_COLOR=1
|
||||
oh-my-logo "GitType" purple
|
||||
echo
|
||||
echo '"Show your AI who'\''s boss: just you, your keyboard,'
|
||||
echo ' and your coding sins"'
|
||||
echo
|
||||
echo "────────────────────────────────────────────────"
|
||||
echo
|
||||
echo "Turn your own source code into typing challenges"
|
||||
echo
|
||||
echo "[*] Addictive gameplay [>] Real-time feedback [+] Track your progress"
|
||||
echo
|
||||
echo "$ brew install gittype"
|
||||
echo "$ gittype"
|
||||
echo
|
||||
echo "github.com/unhappychoice/gittype"
|
||||
|
||||
# To regenerate the banner:
|
||||
# chmod +x docs/images/banner-source.sh
|
||||
# freeze --execute "docs/images/banner-source.sh" -o docs/images/gittype-banner.svg \
|
||||
# --theme "Dracula" --window --background="#1e1e2e" --margin 20 --padding 20 --border.radius 15
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 64 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 13 KiB |
@@ -0,0 +1,53 @@
|
||||
# Installation Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rust 1.70 or later
|
||||
- Git (for repository access)
|
||||
|
||||
## Install from Source
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/unhappychoice/gittype.git
|
||||
cd gittype
|
||||
|
||||
# Build and install
|
||||
cargo build --release
|
||||
cargo install --path .
|
||||
```
|
||||
|
||||
## Install from Cargo
|
||||
|
||||
```bash
|
||||
cargo install gittype
|
||||
```
|
||||
|
||||
## Verify Installation
|
||||
|
||||
```bash
|
||||
gittype --version
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Rust version too old**
|
||||
```bash
|
||||
rustup update stable
|
||||
```
|
||||
|
||||
2. **Permission denied**
|
||||
```bash
|
||||
# On macOS/Linux, ensure cargo bin is in PATH
|
||||
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
3. **Build failures**
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
cargo clean
|
||||
cargo build --release
|
||||
```
|
||||
@@ -0,0 +1,89 @@
|
||||
# Supported Languages
|
||||
|
||||
## Current Support
|
||||
|
||||
| Language | Extension | Status | Tree-sitter Grammar |
|
||||
|----------|-----------|--------|-------------------|
|
||||
| Rust | `.rs` | ✅ Full support | `tree-sitter-rust` |
|
||||
| TypeScript | `.ts`, `.tsx` | ✅ Full support | `tree-sitter-typescript` |
|
||||
| Python | `.py` | ✅ Full support | `tree-sitter-python` |
|
||||
|
||||
## Extraction Features
|
||||
|
||||
### Rust
|
||||
- Functions (`fn`)
|
||||
- Implementations (`impl`)
|
||||
- Structs (`struct`)
|
||||
- Enums (`enum`)
|
||||
- Traits (`trait`)
|
||||
- Modules (`mod`)
|
||||
|
||||
### TypeScript
|
||||
- Functions (`function`)
|
||||
- Classes (`class`)
|
||||
- Interfaces (`interface`)
|
||||
- Methods
|
||||
- Arrow functions
|
||||
- Type definitions (`type`)
|
||||
|
||||
### Python
|
||||
- Functions (`def`)
|
||||
- Classes (`class`)
|
||||
- Methods
|
||||
- Decorators
|
||||
- Lambda functions
|
||||
|
||||
## Planned Support
|
||||
|
||||
| Language | Priority | Expected | Notes |
|
||||
|----------|----------|----------|--------|
|
||||
| JavaScript | High | Next release | ESM/CommonJS support |
|
||||
| Swift | High | Q1 2025 | iOS/macOS development |
|
||||
| Kotlin | High | Q1 2025 | Android/JVM support |
|
||||
| Ruby | High | Q1 2025 | Rails patterns, blocks |
|
||||
| Go | Medium | Q2 2025 | Goroutines, interfaces |
|
||||
| Java | Medium | Q2 2025 | Spring Boot patterns |
|
||||
| C++ | Medium | Q3 2025 | Modern C++17/20 |
|
||||
| C# | Medium | Q3 2025 | .NET 6+ features |
|
||||
| PHP | Low | Future | Laravel/Symfony |
|
||||
| Dart | Low | Future | Flutter development |
|
||||
|
||||
## Language-Specific Options
|
||||
|
||||
### Filtering by Language
|
||||
|
||||
```bash
|
||||
# Single language
|
||||
gittype --langs rust
|
||||
|
||||
# Multiple languages
|
||||
gittype --langs rust,typescript,python
|
||||
```
|
||||
|
||||
### Configuration File
|
||||
|
||||
```toml
|
||||
[default]
|
||||
langs = ["rust", "typescript"]
|
||||
```
|
||||
|
||||
## Code Extraction Quality
|
||||
|
||||
### What Gets Extracted
|
||||
|
||||
- **Complete Functions**: Full function definitions with signatures
|
||||
- **Class Definitions**: Complete class structures
|
||||
- **Method Bodies**: Individual methods and their implementations
|
||||
- **Self-Contained Blocks**: Code that makes sense in isolation
|
||||
|
||||
### What Gets Filtered Out
|
||||
|
||||
- **Incomplete Snippets**: Partial code that lacks context
|
||||
- **Comments Only**: Blocks with only comments
|
||||
- **Import Statements**: Standalone import/use declarations
|
||||
- **Very Short Code**: Code blocks under minimum threshold
|
||||
- **Very Long Code**: Code blocks exceeding `--max-lines`
|
||||
|
||||
## Adding New Language Support
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md#adding-language-support) for detailed instructions on adding support for new programming languages.
|
||||
@@ -0,0 +1,87 @@
|
||||
# Usage Guide
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Navigate to any code repository:**
|
||||
```bash
|
||||
cd /path/to/your/project
|
||||
```
|
||||
|
||||
2. **Start typing practice:**
|
||||
```bash
|
||||
gittype
|
||||
```
|
||||
|
||||
3. **Or specify a specific repository:**
|
||||
```bash
|
||||
gittype /path/to/another/repo
|
||||
```
|
||||
|
||||
## Command Line Options
|
||||
|
||||
```bash
|
||||
gittype [OPTIONS] [REPO_PATH] [COMMAND]
|
||||
```
|
||||
|
||||
### Basic Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--langs` | Filter by programming languages (comma-separated) | All supported |
|
||||
| `--include` | Glob patterns for files to include | All files |
|
||||
| `--exclude` | Glob patterns for files to exclude | None |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Practice with Rust and TypeScript files only
|
||||
gittype --langs rust,typescript
|
||||
|
||||
# Include only source files, exclude tests
|
||||
gittype --include "src/**" --exclude "**/tests/**"
|
||||
|
||||
# Exclude multiple patterns
|
||||
gittype --exclude "**/tests/**" --exclude "**/node_modules/**"
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### View Session History
|
||||
```bash
|
||||
gittype history
|
||||
```
|
||||
|
||||
### Show Analytics
|
||||
```bash
|
||||
gittype stats
|
||||
```
|
||||
|
||||
### Export Session Data
|
||||
```bash
|
||||
gittype export
|
||||
```
|
||||
|
||||
## Game Interface
|
||||
|
||||
### Controls
|
||||
|
||||
- **Type**: Simply start typing to begin
|
||||
- **Ctrl+C**: Exit current session
|
||||
- **Tab**: Skip current challenge (if available)
|
||||
- **Enter**: Confirm completion
|
||||
|
||||
### Scoring
|
||||
|
||||
- **Accuracy**: Percentage of correct characters
|
||||
- **WPM**: Words per minute (based on 5 characters per word)
|
||||
- **CPM**: Characters per minute
|
||||
- **Mistakes**: Number of incorrect keystrokes
|
||||
|
||||
### Challenge Flow
|
||||
|
||||
1. **Title Screen**: Welcome and instructions
|
||||
2. **Loading Screen**: Extracting code chunks
|
||||
3. **Countdown**: 3-2-1 start
|
||||
4. **Typing Challenge**: Type the displayed code
|
||||
5. **Results**: View performance metrics
|
||||
6. **Next Challenge**: Continue to next stage
|
||||
Reference in New Issue
Block a user