From ad00995b6a73dbfd7067e8ee94d16e23a8e8822f Mon Sep 17 00:00:00 2001 From: Juan Rodriguez Date: Wed, 18 Mar 2026 14:59:41 +0100 Subject: [PATCH 1/2] add cursor rules --- .cursor/ARCHITECTURE.md | 398 ++++++++++++++++++ .cursor/PULL_REQUEST_TEMPLATE.md | 38 ++ .cursor/README.md | 276 ++++++++++++ .cursor/_TEMPLATE_general-rule.md | 38 ++ .cursor/commands/smart-commit.md | 24 ++ .cursor/commands/smart-pr.md | 209 +++++++++ .cursor/copilot-instructions.md | 127 ++++++ .cursor/rules/commit-guidelines.md | 111 +++++ .cursor/rules/model.instructions.md | 97 +++++ .cursor/rules/pull-request-guidelines.md | 186 ++++++++ .cursor/rules/verification-guidelines.md | 38 ++ .cursor/skills/assets-management/SKILL.md | 49 +++ .../references/assets-management.md | 135 ++++++ .../skills/localization-management/SKILL.md | 57 +++ .../references/localization-management.md | 75 ++++ .cursor/skills/pr-review/SKILL.md | 152 +++++++ .cursor/skills/swift-coding-style/SKILL.md | 78 ++++ .../examples/access-control.md | 29 ++ .../swift-coding-style/examples/clean-code.md | 30 ++ .../swift-coding-style/examples/constants.md | 15 + .../examples/control-flow.md | 32 ++ .../examples/memory-management.md | 29 ++ .../examples/protocol-extensions.md | 29 ++ .../examples/protocol-organization.md | 29 ++ .../examples/type-inference.md | 11 + .../skills/swift-concurrency-expert/SKILL.md | 37 ++ .../references/approachable-concurrency.md | 63 +++ .../references/swift-6-2-concurrency.md | 272 ++++++++++++ .../swiftui-concurrency-tour-wwdc.md | 33 ++ .../skills/swift-testing-guidelines/SKILL.md | 41 ++ .../examples/class-mock.md | 41 ++ .../examples/object-mother-pattern.md | 29 ++ .../examples/swift-testing-parameterized.md | 25 ++ .../examples/unit-tests-naming.md | 8 + .../examples/unit-tests-structure.md | 24 ++ .cursor/skills/swiftui-liquid-glass/SKILL.md | 90 ++++ .../references/liquid-glass.md | 318 ++++++++++++++ .../skills/swiftui-performance-audit/SKILL.md | 187 ++++++++ .../demystify-swiftui-performance-wwdc23.md | 46 ++ ...imizing-swiftui-performance-instruments.md | 29 ++ .../understanding-hangs-in-your-app.md | 33 ++ ...rstanding-improving-swiftui-performance.md | 52 +++ .cursor/skills/swiftui-ui-patterns/SKILL.md | 95 +++++ .../references/app-wiring.md | 194 +++++++++ .../references/components-index.md | 43 ++ .../references/controls.md | 57 +++ .../references/deeplinks.md | 66 +++ .../swiftui-ui-patterns/references/focus.md | 91 ++++ .../swiftui-ui-patterns/references/form.md | 97 +++++ .../swiftui-ui-patterns/references/grids.md | 71 ++++ .../swiftui-ui-patterns/references/haptics.md | 71 ++++ .../references/input-toolbar.md | 51 +++ .../references/lightweight-clients.md | 93 ++++ .../swiftui-ui-patterns/references/list.md | 86 ++++ .../references/loading-placeholders.md | 38 ++ .../references/macos-settings.md | 71 ++++ .../references/matched-transitions.md | 66 +++ .../swiftui-ui-patterns/references/media.md | 73 ++++ .../references/menu-bar.md | 101 +++++ .../references/navigationstack.md | 159 +++++++ .../swiftui-ui-patterns/references/overlay.md | 45 ++ .../references/scrollview.md | 87 ++++ .../references/searchable.md | 71 ++++ .../swiftui-ui-patterns/references/sheets.md | 113 +++++ .../references/split-views.md | 72 ++++ .../swiftui-ui-patterns/references/tabview.md | 114 +++++ .../swiftui-ui-patterns/references/theming.md | 71 ++++ .../references/title-menus.md | 93 ++++ .../swiftui-ui-patterns/references/top-bar.md | 43 ++ .cursor/skills/swiftui-view-refactor/SKILL.md | 136 ++++++ .../references/mv-patterns.md | 314 ++++++++++++++ .gitignore | 5 +- 72 files changed, 6303 insertions(+), 4 deletions(-) create mode 100644 .cursor/ARCHITECTURE.md create mode 100644 .cursor/PULL_REQUEST_TEMPLATE.md create mode 100644 .cursor/README.md create mode 100644 .cursor/_TEMPLATE_general-rule.md create mode 100644 .cursor/commands/smart-commit.md create mode 100644 .cursor/commands/smart-pr.md create mode 100644 .cursor/copilot-instructions.md create mode 100644 .cursor/rules/commit-guidelines.md create mode 100644 .cursor/rules/model.instructions.md create mode 100644 .cursor/rules/pull-request-guidelines.md create mode 100644 .cursor/rules/verification-guidelines.md create mode 100644 .cursor/skills/assets-management/SKILL.md create mode 100644 .cursor/skills/assets-management/references/assets-management.md create mode 100644 .cursor/skills/localization-management/SKILL.md create mode 100644 .cursor/skills/localization-management/references/localization-management.md create mode 100644 .cursor/skills/pr-review/SKILL.md create mode 100644 .cursor/skills/swift-coding-style/SKILL.md create mode 100644 .cursor/skills/swift-coding-style/examples/access-control.md create mode 100644 .cursor/skills/swift-coding-style/examples/clean-code.md create mode 100644 .cursor/skills/swift-coding-style/examples/constants.md create mode 100644 .cursor/skills/swift-coding-style/examples/control-flow.md create mode 100644 .cursor/skills/swift-coding-style/examples/memory-management.md create mode 100644 .cursor/skills/swift-coding-style/examples/protocol-extensions.md create mode 100644 .cursor/skills/swift-coding-style/examples/protocol-organization.md create mode 100644 .cursor/skills/swift-coding-style/examples/type-inference.md create mode 100644 .cursor/skills/swift-concurrency-expert/SKILL.md create mode 100644 .cursor/skills/swift-concurrency-expert/references/approachable-concurrency.md create mode 100644 .cursor/skills/swift-concurrency-expert/references/swift-6-2-concurrency.md create mode 100644 .cursor/skills/swift-concurrency-expert/references/swiftui-concurrency-tour-wwdc.md create mode 100644 .cursor/skills/swift-testing-guidelines/SKILL.md create mode 100644 .cursor/skills/swift-testing-guidelines/examples/class-mock.md create mode 100644 .cursor/skills/swift-testing-guidelines/examples/object-mother-pattern.md create mode 100644 .cursor/skills/swift-testing-guidelines/examples/swift-testing-parameterized.md create mode 100644 .cursor/skills/swift-testing-guidelines/examples/unit-tests-naming.md create mode 100644 .cursor/skills/swift-testing-guidelines/examples/unit-tests-structure.md create mode 100644 .cursor/skills/swiftui-liquid-glass/SKILL.md create mode 100644 .cursor/skills/swiftui-liquid-glass/references/liquid-glass.md create mode 100644 .cursor/skills/swiftui-performance-audit/SKILL.md create mode 100644 .cursor/skills/swiftui-performance-audit/references/demystify-swiftui-performance-wwdc23.md create mode 100644 .cursor/skills/swiftui-performance-audit/references/optimizing-swiftui-performance-instruments.md create mode 100644 .cursor/skills/swiftui-performance-audit/references/understanding-hangs-in-your-app.md create mode 100644 .cursor/skills/swiftui-performance-audit/references/understanding-improving-swiftui-performance.md create mode 100644 .cursor/skills/swiftui-ui-patterns/SKILL.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/app-wiring.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/components-index.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/controls.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/deeplinks.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/focus.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/form.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/grids.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/haptics.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/input-toolbar.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/lightweight-clients.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/list.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/loading-placeholders.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/macos-settings.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/matched-transitions.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/media.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/menu-bar.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/navigationstack.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/overlay.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/scrollview.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/searchable.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/sheets.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/split-views.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/tabview.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/theming.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/title-menus.md create mode 100644 .cursor/skills/swiftui-ui-patterns/references/top-bar.md create mode 100644 .cursor/skills/swiftui-view-refactor/SKILL.md create mode 100644 .cursor/skills/swiftui-view-refactor/references/mv-patterns.md diff --git a/.cursor/ARCHITECTURE.md b/.cursor/ARCHITECTURE.md new file mode 100644 index 0000000..4ae5a3f --- /dev/null +++ b/.cursor/ARCHITECTURE.md @@ -0,0 +1,398 @@ +# Fever Rules Architecture + +## System Overview + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ FEVER RULES SYSTEM │ +└─────────────────────────────────────────────────────────────────────┘ + +┌──────────────────────────────────┐ +│ .feverrules/ │ ← SINGLE SOURCE OF TRUTH +│ │ (Edit rules here only) +│ ├─ rules/ │ +│ │ └─ *.mdc │ +│ ├─ commands/ │ +│ │ └─ *.md │ +│ └─ *.md (root) │ +└────────┬─────────────────────────┘ + │ + │ Run: make sync-rules + │ or: python3 scripts/sync_rules.py + │ + ▼ +┌────────────────────────────────────────────────────────────────┐ +│ scripts/sync_rules.py │ +│ │ +│ • Validates directories │ +│ • Reads .feverrules/rules/ and .feverrules/commands/ │ +│ • Determines target locations │ +│ • Copies files to targets │ +│ • Reports sync status │ +└──────┬───────────────┬──────────────────────────┬──────────────┘ + │ │ │ + ▼ ▼ ▼ +┌─────────────┐ ┌─────────────────┐ ┌──────────────────────────────────┐ +│.cursor/ │ │.cursor/ │ │ .github/ │ +│ rules/ │ │ commands/ │ │ │ +│ └─ *.mdc │ │ └─ *.md │ │ ├─ copilot-instructions.md │ +│ │ │ │ │ │ (auto-generated) │ +│ (Cursor │ │ (Cursor │ │ ├─ instructions/ │ +│ rules) │ │ commands) │ │ │ └─ *.instructions.md │ +└─────────────┘ └─────────────────┘ │ └─ PULL_REQUEST_TEMPLATE.md │ + │ │ + │ (GitHub Copilot files) │ + └──────────────────────────────────┘ +``` + +## Data Flow + +### 1. Creation/Update Flow + +``` +Developer + │ + ├─► Edit .feverrules/rules/commit-guidelines.mdc + │ + └─► Run: make sync-rules + │ + ▼ + sync_rules.py + │ + ├─► Copy to .cursor/rules/commit-guidelines.mdc + │ + └─► Report: "✓ Synced: commit-guidelines.mdc" +``` + +### 2. File Type Routing + +``` +.feverrules/ + │ + ├─ rules/*.mdc ──────────────────► .cursor/rules/ (individual files) + │ (Cursor AI rules) .github/copilot-instructions.md (concatenated) + │ + ├─ commands/*.md ────────────────► .cursor/commands/ + │ (Cursor commands) + │ + ├─ instructions/*.instructions.md ► .github/instructions/ + │ (Path-specific Copilot) + │ + └─ *.md (root files) ────────────► .github/ + (GitHub templates - flat) + Examples: + • PULL_REQUEST_TEMPLATE.md +``` + +## Component Details + +### 1. Source Directory (`.feverrules/`) + +**Purpose**: Single source of truth for all project rules + +**Structure**: +``` +.feverrules/ +├── rules/ # All rules (general + path-specific) +│ ├── commit-guidelines.mdc → .cursor/rules/ + copilot-instructions.md +│ ├── pull-request-guidelines.mdc → .cursor/rules/ + copilot-instructions.md +│ └── model.instructions.md → .github/instructions/ (path-specific) +├── commands/ # Cursor commands +│ ├── smart-commit.md → .cursor/commands/ +│ └── smart-pr.md → .cursor/commands/ +├── PULL_REQUEST_TEMPLATE.md → .github/ +└── README.md # This file +``` + +**Rules**: +- ✅ Always edit files here +- ❌ Never edit target directories directly +- ✅ All rules in `rules/` folder (both `.mdc` and `.instructions.md`) +- ✅ Commands in `commands/` folder +- ✅ Templates in root +- ✅ Only 2 folders: `rules/` + `commands/` + +### 2. Sync Script (`scripts/sync_rules.py`) + +**Purpose**: Automate copying rules to target locations + +**Features**: +- Validates source and target directories +- Creates missing directories automatically +- Determines target location based on file type +- Skips unchanged files (optimization) +- Provides clear feedback +- Error handling and validation + +**Algorithm**: +```python +for each file in .feverrules/: + if file.extension == ".mdc": + target = .cursor/rules/ + elif file.name == "PULL_REQUEST_TEMPLATE.md": + target = .github/ + else: + skip file + + if file content != target content: + copy file to target + report "Synced" + else: + report "Already up to date" +``` + +### 3. Target Directories + +#### `.cursor/rules/` +- **Purpose**: Cursor AI rules for code assistance +- **File types**: `.mdc` files +- **Usage**: Cursor AI reads these for context +- **Source**: `.feverrules/rules/` +- **Managed by**: sync script (DO NOT EDIT) + +#### `.cursor/commands/` +- **Purpose**: Custom Cursor commands +- **File types**: `.md` files +- **Usage**: Cursor command palette +- **Source**: `.feverrules/commands/` +- **Managed by**: sync script (DO NOT EDIT) + +#### `.github/` +- **Purpose**: GitHub templates and Copilot configuration +- **File types**: Markdown files +- **Usage**: GitHub uses for PR creation and Copilot instructions +- **Source**: `.feverrules/` (root files and subdirectories) +- **Managed by**: sync script (DO NOT EDIT) +- **Structure**: + - `copilot-instructions.md` - Auto-generated from all `rules/*.mdc` files + - `instructions/*.instructions.md` - Path-specific instructions from `.feverrules/instructions/` + - `PULL_REQUEST_TEMPLATE.md` - PR template from `.feverrules/` + +## Sync Process Details + +### Step-by-Step Execution + +``` +1. Validate Directories + ├─ Check .feverrules/ exists + ├─ Check/create .feverrules/rules/ + ├─ Check/create .feverrules/commands/ + ├─ Check/create .cursor/rules/ + ├─ Check/create .cursor/commands/ + └─ Check/create .github/ + +2. Discover Files + ├─ Scan .feverrules/rules/ for *.mdc files + ├─ Scan .feverrules/commands/ for *.md files + ├─ Check .feverrules/ root for template files + └─ Build (source, target) pairs + +3. Sync Each File + ├─ Read source content + ├─ Read target content (if exists) + ├─ Compare contents + ├─ Copy if different + └─ Report status + +4. Summary + ├─ Count successful syncs + ├─ Count skipped files + └─ Exit with status code +``` + +### File Type Mapping + +| Source Pattern | Target Directory | Example | +|---------------|------------------|---------| +| `rules/*.mdc` | `.cursor/rules/` + `.github/copilot-instructions.md` | `rules/commit-guidelines.mdc` → `.cursor/rules/` + concatenated | +| `commands/*.md` | `.cursor/commands/` | `commands/smart-commit.md` → `.cursor/commands/smart-commit.md` | +| `instructions/*.instructions.md` | `.github/instructions/` | `instructions/viewmodel.instructions.md` → `.github/instructions/viewmodel.instructions.md` | +| `PULL_REQUEST_TEMPLATE.md` | `.github/` | `PULL_REQUEST_TEMPLATE.md` → `.github/PULL_REQUEST_TEMPLATE.md` | +| `README.md` | (skipped) | Documentation only | + +## Usage Patterns + +### Pattern 1: Update Existing Rule + +```bash +# 1. Edit source +vim .feverrules/rules/commit-guidelines.mdc + +# 2. Sync +make sync-rules + +# 3. Verify +git diff .cursor/rules/commit-guidelines.mdc + +# 4. Commit +git add .feverrules/ .cursor/ +git commit -m "[TICKET] docs: update commit guidelines" +``` + +### Pattern 2: Add New Rule + +```bash +# 1. Create new rule +cat > .feverrules/rules/new-rule.mdc << 'EOF' +--- +description: New rule description +alwaysApply: false +--- +# New Rule +... +EOF + +# 2. Sync +make sync-rules + +# 3. Commit +git add .feverrules/ .cursor/ +git commit -m "[TICKET] docs: add new rule" +``` + +### Pattern 3: Add New Command + +```bash +# 1. Create new command +cat > .feverrules/commands/new-command.md << 'EOF' +# New Command Description +... +EOF + +# 2. Sync +make sync-rules + +# 3. Commit +git add .feverrules/ .cursor/ +git commit -m "[TICKET] docs: add new command" +``` + +### Pattern 4: Bulk Update + +```bash +# 1. Edit multiple files +vim .feverrules/rules/commit-guidelines.mdc +vim .feverrules/rules/pull-request-guidelines.mdc + +# 2. Sync all at once +make sync-rules + +# 3. Review all changes +git diff .cursor/ + +# 4. Commit together +git add .feverrules/ .cursor/ +git commit -m "[TICKET] docs: update multiple rules" +``` + +## Error Handling + +### Missing Source Directory +``` +❌ Error: Source directory not found: .feverrules +``` +**Solution**: Create `.feverrules/` directory + +### Permission Issues +``` +❌ Error syncing file.mdc: Permission denied +``` +**Solution**: Check file permissions + +### No Files to Sync +``` +⚠️ No files found to sync in .feverrules +``` +**Solution**: Add `.mdc` or template files + +## Extension Points + +### Adding New Target Directories + +To add support for new target directories, modify `sync_rules.py`: + +```python +def get_files_to_sync(self) -> List[Tuple[Path, Path]]: + # ... existing code ... + + # Add new target + elif file_path.name == "NEW_TEMPLATE.md": + target_path = self.new_target_dir / file_path.name + files_to_sync.append((file_path, target_path)) +``` + +### Adding New File Types + +```python +# In __init__ +self.new_target_dir = project_root / ".newtarget" + +# In get_files_to_sync +elif file_path.suffix == ".newext": + target_path = self.new_target_dir / file_path.name + files_to_sync.append((file_path, target_path)) +``` + +## Best Practices + +1. **Always use the sync script** - Never manually copy files +2. **Commit atomically** - Source and targets together +3. **Verify after sync** - Check git diff before committing +4. **Document changes** - Use clear commit messages +5. **Test locally** - Run sync before pushing + +## Troubleshooting + +### Sync not updating files + +**Check**: +```bash +# Compare files manually +diff .feverrules/commit-guidelines.mdc .cursor/rules/commit-guidelines.mdc +``` + +**Solution**: Ensure you saved the source file + +### Files out of sync + +**Check**: +```bash +# Run sync with verbose output +python3 scripts/sync_rules.py +``` + +**Solution**: Re-run sync script + +### Git shows unexpected changes + +**Check**: +```bash +# View what changed +git diff .cursor/rules/ +``` + +**Solution**: Review changes and commit if correct + +## Performance Considerations + +- **File comparison**: Script compares content before copying (efficient) +- **Skips unchanged**: Only copies when content differs +- **Fast execution**: Typically completes in < 1 second +- **Scalable**: Can handle dozens of rules without issues + +## Security Considerations + +- Source files are plain text (no secrets) +- Sync script only reads/writes local files +- No network operations +- Safe to run in CI/CD pipelines + +## Future Enhancements + +Potential improvements: +- [ ] Dry-run mode (`--dry-run`) +- [ ] Verbose mode (`--verbose`) +- [ ] Watch mode (auto-sync on file change) +- [ ] Validation of rule syntax +- [ ] Pre-commit hook integration +- [ ] Backup before sync diff --git a/.cursor/PULL_REQUEST_TEMPLATE.md b/.cursor/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d7d1dc2 --- /dev/null +++ b/.cursor/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,38 @@ +# ℹ️ Context + +* + +# 👷 Changes + +* + +## ❓ Questions + +* + +## ⚠️ Trade-offs & Tech Debt + +* + +# 🧪 How to Test + + +## 📝 Instructions +1. Checkout this branch: `git checkout ` +2. Build the project in Xcode +3. Test on: + * iPhone 14 Pro (iOS 18.0, simulator) + * iPad Air (real device, iOS 17.5) +4. Steps: + - Go to screen X + - Tap Y + - Verify Z happens + +## 📱 Screenshots / Videos + +| Before | After | +|--------|-------| +| img1 | img2 | diff --git a/.cursor/README.md b/.cursor/README.md new file mode 100644 index 0000000..c7c0f2a --- /dev/null +++ b/.cursor/README.md @@ -0,0 +1,276 @@ +# Fever Rules - Centralized Rule Management + +This directory contains the **source of truth** for all project rules and templates that are used across different tools and platforms. + +## 📁 Directory Structure + +``` +.feverrules/ (SOURCE OF TRUTH - EDIT HERE) +├── rules/ → .cursor/rules/ + .github/ +│ ├── *.mdc → .cursor/rules/ + copilot-instructions.md (concatenated) +│ └── *.instructions.md → .github/instructions/ (path-specific) +├── commands/ → .cursor/commands/ +│ ├── smart-commit.md +│ └── smart-pr.md +├── PULL_REQUEST_TEMPLATE.md → .github/PULL_REQUEST_TEMPLATE.md +└── README.md (this file) +``` + +## 🎯 Purpose + +The `.feverrules` directory serves as a centralized location for maintaining project rules. Instead of manually updating rules in multiple locations (`.cursor/rules/`, `.github/`, etc.), you only need to update them here and run the sync script. + +## 🔄 How It Works + +1. **Edit rules** in `.feverrules/` directory +2. **Run sync script** to propagate changes: + ```bash + python3 scripts/sync_rules.py + ``` +3. **Commit changes** to both `.feverrules/` and target directories + +## 📝 File Types & How They Sync + +### Rules Folder (`rules/`) + +The `rules/` folder contains **all** types of rules: + +#### General Rules (`rules/*.mdc`) +Files with `.mdc` extension are general Cursor AI rules. + +**Syncs to:** +- ✅ `.cursor/rules/` - Individual files (for Cursor IDE) +- ✅ `.github/copilot-instructions.md` - Concatenated (for GitHub Copilot) + +**Current rules:** +- `rules/commit-guidelines.mdc` - Commit message conventions +- `rules/pull-request-guidelines.mdc` - PR creation guidelines + +**When you add a new rule:** +1. Add `.mdc` file to `.feverrules/rules/` +2. Run `make sync-rules` +3. Auto-appears in `.cursor/rules/` AND `.github/copilot-instructions.md` + +#### Path-Specific Instructions (`rules/*.instructions.md`) +Files with `.instructions.md` extension are path-specific GitHub Copilot instructions. + +**Syncs to:** +- ✅ `.github/instructions/` - Path-specific (GitHub Copilot only) + +**How it works:** +- Use frontmatter with `applyTo` glob pattern +- Applies ONLY to files matching the pattern +- NOT concatenated into copilot-instructions.md + +**Current instructions:** +- `rules/model.instructions.md` - Modern @Perceptible pattern for Models + - `applyTo: "FeverApp/Sources/**/*Model.swift"` + +**Example:** +```markdown +--- +applyTo: "FeverApp/Sources/**/*Repository.swift" +--- + +# Repository Guidelines +... +``` + +### Cursor Commands (`commands/*.md`) +Markdown files in the `commands/` subdirectory define custom Cursor commands. + +**Syncs to:** +- ✅ `.cursor/commands/` - Individual files (for Cursor IDE) + +**Current commands:** +- `commands/smart-commit.md` - Smart commit command +- `commands/smart-pr.md` - Smart PR creation command + +### GitHub Templates (root files) +Templates in the root of `.feverrules/` that sync to `.github/`. + +**Current templates:** +- `PULL_REQUEST_TEMPLATE.md` - Template for pull requests + +## 🛠️ Sync Script + +The sync script (`scripts/sync_rules.py`) automatically: +- ✅ **Auto-generates** `.github/copilot-instructions.md` by concatenating all `rules/*.mdc` files +- ✅ Copies `rules/*.mdc` files to `.cursor/rules/` (individual files) +- ✅ Copies `commands/*.md` files to `.cursor/commands/` +- ✅ Copies `instructions/*.instructions.md` files to `.github/instructions/` (path-specific) +- ✅ Copies `PULL_REQUEST_TEMPLATE.md` to `.github/` +- ✅ Validates that required directories exist +- ✅ Creates missing directories if needed +- ✅ Skips files that are already up to date +- ✅ Provides clear feedback on what was synced + +### Usage + +```bash +# Using Make (recommended) +make sync-rules + +# Or directly with Python +python3 scripts/sync_rules.py +``` + +### Output Example + +``` +Project root: /Users/ibrahim.koteish@feverup.com/Documents/fever/iOS + +🔄 Starting rules sync... + +📝 Generating .github/copilot-instructions.md from rules... +✓ Generated: copilot-instructions.md (auto-generated from 2 rule(s)) + +Found 5 file(s) to sync + +✓ Already up to date: .cursor/rules/commit-guidelines.mdc +✓ Already up to date: .cursor/rules/pull-request-guidelines.mdc +✓ Already up to date: .cursor/commands/smart-commit.md +✓ Already up to date: .cursor/commands/smart-pr.md +✓ Already up to date: .github/PULL_REQUEST_TEMPLATE.md + +============================================================ +Sync complete: 5/5 files synced successfully +✓ Generated 1 file (copilot-instructions.md) +============================================================ +``` + +## 📋 Adding New Rules + +To add a new rule: + +1. **Create the file** in `.feverrules/rules/`: + ```bash + vim .feverrules/rules/new-rule.mdc + ``` + +2. **Run the sync script**: + ```bash + make sync-rules + ``` + +3. **Result**: + - ✅ Copied to `.cursor/rules/new-rule.mdc` + - ✅ Auto-included in `.github/copilot-instructions.md` + +4. **Commit**: + ```bash + git add .feverrules/ .cursor/ .github/ + git commit -m "[TICKET] docs: add new rule" + ``` + +## 🔍 Workflow Examples + +### Updating Existing Rules + +```bash +# 1. Edit the rule in .feverrules/rules/ +vim .feverrules/rules/commit-guidelines.mdc + +# 2. Sync to target directories +make sync-rules + +# 3. Verify changes +git diff .cursor/rules/commit-guidelines.mdc +git diff .github/copilot-instructions.md + +# 4. Commit +git add .feverrules/ .cursor/ .github/ +git commit -m "[TICKET] docs: update commit guidelines" +``` + +### Adding New Rules + +```bash +# 1. Create new rule file +cat > .feverrules/rules/code-style.mdc << 'EOF' +--- +description: Code style guidelines for Swift development +alwaysApply: false +--- +# Code Style Guidelines +... +EOF + +# 2. Sync (auto-generates copilot-instructions.md) +make sync-rules + +# 3. Commit +git add .feverrules/ .cursor/ .github/ +git commit -m "[TICKET] docs: add code style guidelines" +``` + +### Adding New Commands + +```bash +# 1. Create new command +vim .feverrules/commands/new-command.md + +# 2. Sync +make sync-rules + +# 3. Commit +git add .feverrules/ .cursor/ +git commit -m "[TICKET] docs: add new command" +``` + +### Adding Path-Specific Instructions + +```bash +# 1. Create instruction file in rules/ folder with frontmatter +cat > .feverrules/rules/repository.instructions.md << 'EOF' +--- +applyTo: "FeverApp/Sources/**/*Repository.swift" +--- + +# Repository Guidelines +- Use protocol-based design +- Handle errors appropriately +... +EOF + +# 2. Sync +make sync-rules + +# 3. Commit +git add .feverrules/ .github/ +git commit -m "[TICKET] docs: add repository instructions" +``` + +## ⚠️ Important Notes + +1. **Always edit in `.feverrules/`**: Never edit files directly in `.cursor/rules/` or `.github/` as they will be overwritten by the sync script. + +2. **`.github/copilot-instructions.md` is auto-generated**: This file is automatically created by concatenating all `rules/*.mdc` files. Don't edit it manually! + +3. **Run sync before committing**: Always run `make sync-rules` after making changes to ensure all target directories are up to date. + +4. **Commit all changes together**: When you update a rule, commit both `.feverrules/`, `.cursor/`, and `.github/`. + +5. **Check sync output**: The sync script tells you which files were updated and which were already up to date. + +## 🚀 Benefits + +- ✅ **Single source of truth**: All rules in `.feverrules/rules/` and `.feverrules/commands/` +- ✅ **Auto-generation**: `.github/copilot-instructions.md` auto-generated from rules +- ✅ **Consistency**: Same rules work in Cursor and GitHub Copilot +- ✅ **Easy updates**: Add new rule → run sync → done +- ✅ **Version control**: Track all rule changes in git +- ✅ **No manual copying**: Script handles everything + +## 🔗 Related Files + +- **Source**: `.feverrules/` (edit here) +- **Sync Script**: `scripts/sync_rules.py` +- **Targets**: `.cursor/` and `.github/` (auto-synced) +- **Command**: `make sync-rules` + +## 📚 Further Reading + +- [Cursor Documentation](https://cursor.sh/docs) +- [GitHub Copilot Instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) +- Main project README: `../README.md` diff --git a/.cursor/_TEMPLATE_general-rule.md b/.cursor/_TEMPLATE_general-rule.md new file mode 100644 index 0000000..c3ce296 --- /dev/null +++ b/.cursor/_TEMPLATE_general-rule.md @@ -0,0 +1,38 @@ + + + + +# Rule Name + +> **Note**: Change `applyTo` to: +> - `"**"` for general rules (all files) +> - `"FeverApp/Sources/**/*YourPattern.swift"` for specific files + +## Purpose +Describe what this rule is for. + +## Guidelines +- Guideline 1 +- Guideline 2 +- Guideline 3 + +## Examples + +### Good Example +```swift +// Good code example +``` + +### Bad Example +```swift +// Bad code example +``` + +## Best Practices +- Best practice 1 +- Best practice 2 diff --git a/.cursor/commands/smart-commit.md b/.cursor/commands/smart-commit.md new file mode 100644 index 0000000..73167d3 --- /dev/null +++ b/.cursor/commands/smart-commit.md @@ -0,0 +1,24 @@ +# Smart Commit Command + +This command analyzes staged changes and creates a commit following the project's commit guidelines. + +## How It Works + +When you invoke this command (e.g., via `/smart-commit`), the AI will: + +1. **Get the staged files** using `git diff --cached --name-only` or `git status` +2. **Analyze ONLY the staged changes** using `git diff --cached` - ignore unstaged changes +3. **Read the actual diff** to understand what changed in each staged file +4. **Identify the primary purpose** of the changes from the staged diff +5. **Choose the appropriate type** (feat, fix, refactor, etc.) +6. **Determine the scope** from file paths and changed components in staged files +7. **Write a clear subject line** following the commit guidelines +8. **Add a body** if the changes are complex or need explanation +9. **Include footer** if there are issue references or breaking changes +10. **Execute the commit** using `git commit -m` with the generated message + +The entire process should be automated - analyze, generate, and commit without user intervention. + +## Commit Guidelines + +**IMPORTANT**: This command MUST follow the commit guidelines defined in `.feverrules/rules/commit-guidelines.md`. Please read and apply all guidelines from that file when generating commit messages. diff --git a/.cursor/commands/smart-pr.md b/.cursor/commands/smart-pr.md new file mode 100644 index 0000000..e959f86 --- /dev/null +++ b/.cursor/commands/smart-pr.md @@ -0,0 +1,209 @@ +# Smart PR Command + +This command analyzes the current branch and generates a comprehensive pull request description following the project's pull request guidelines. + +## How It Works + +When you invoke this command (e.g., via `/smart-pr`), the AI will: + +1. **Check for GitHub CLI** using `which gh` or `gh --version` +2. **Get the current branch name** using `git branch --show-current` +3. **Extract the ticket identifier** from the branch name (e.g., PLATFORM-7505) +4. **Get the base branch** (typically `main` or `develop`) by checking common patterns or using `git remote show origin` +5. **Analyze the diff** between the base branch and current branch using `git diff` +6. **Review commit messages** in the current branch using `git log` +7. **Identify changed files** to determine if visual changes exist (UI components, views, etc.) +8. **Generate a PR title** in the format: `[TICKET-ID] Description` +9. **Create comprehensive PR description** with all required sections: + - ℹ️ Context (with ticket link and problem statement) + - 👷 Changes (high-level list of what changed) + - ❓ Questions (optional - areas needing feedback) + - ⚠️ Trade-offs & Tech Debt (important decisions and shortcuts) + - 🧪 How to Test (detailed testing instructions) + - 📱 Screenshots / Videos (only if visual changes detected) +10. **Calculate PR size** based on code-only diff lines (excluding images, docs, and generated files). +11. **Fetch available repository labels** (if GitHub CLI is installed): + - Use `gh label list` to get all labels in the repository + - Analyze label names and descriptions to determine which ones are appropriate for this PR + - Select relevant labels based on: + - Type of change (e.g., feature, bugfix, documentation) + - Any other contextually relevant labels +12. **Create or output the PR**: + - **If GitHub CLI is installed**: Automatically create the PR using `gh pr create` (do NOT use `--web` flag to avoid opening browser) + - **Auto-assign** the PR creator as the assignee using `--assignee @me` + - **Auto-label** with the selected repository labels and the calculated size label + - **If GitHub CLI is NOT installed**: Output the PR title and description in a formatted way for manual copy-paste into GitHub's web interface + - Include a note about the recommended size label and other suggested labels to apply manually + +The command should intelligently: +- Detect if UI files were changed to determine if screenshots section is needed +- Infer the context from commit messages and code changes +- Suggest appropriate testing devices (iOS simulators and real devices) +- Identify potential trade-offs based on code patterns +- Generate the ticket URL automatically (format: https://feverup.atlassian.net/browse/TICKET-ID) +- Calculate size based ONLY on actual code changes (Swift files, config files, etc.) +- Exclude from size calculation: images, *.md files, generated files, and asset diffs +- Adapt behavior based on whether GitHub CLI is available or not + +## Workflow + +``` +1. User invokes /smart-pr +2. Check if 'gh' command is available +3. Analyze current branch and changes +4. Calculate PR size based on code-only diff +5. IF GitHub CLI is available: + → Fetch repository labels: `gh label list` + → Analyze label descriptions and select appropriate ones +6. Generate PR title and description +7. IF GitHub CLI is available: + → Execute `gh pr create` with: + - Generated title and body + - Auto-assign: --assignee @me + - Auto-label: selected repository labels + size label + - Do NOT use --web flag (no browser prompt) + ELSE: + → Output formatted title and description for manual copy-paste + → Include note about recommended size label and other suggested labels +``` + +## Pull Request Guidelines + +**IMPORTANT**: This command MUST follow the pull request guidelines defined in `.feverrules/rules/pull-request-guidelines.md`. Please read and apply all guidelines from that file when generating PR descriptions. + +## Expected Output Format + +### When GitHub CLI is Available + +Execute `gh pr create` command with the generated title and body. The command MUST include: + +**Required flags:** +- `--title` for the PR title (format: `[TICKET-ID] Description`) +- `--body` for the PR description (following PR template structure) +- `--assignee @me` to auto-assign the PR creator +- `--label` for comma-separated labels, including: + - Size label (e.g., `size/m`) + - Contextually relevant labels from `gh label list` based on their descriptions +- `--base` to specify the target branch (if not default) + +**Important:** +- Do NOT use `--web` flag (avoid opening browser/prompting web interface) +- Handle errors gracefully (e.g., not authenticated, remote not set up) + +**Example command:** +```bash +gh pr create \ + --title "[PLATFORM-7505] Add multi-category event filtering" \ + --body "" \ + --assignee @me \ + --label "feature,size/m" \ + --base main +``` + +Note: The labels are intelligently selected from the repository's available labels based on their descriptions and the PR's content. + +### When GitHub CLI is NOT Available + +Display a clear, formatted output with sections for manual copy-paste: + +1. **Installation Suggestion**: Inform the user they can install GitHub CLI with: `brew install gh` +2. **PR Title**: Show the generated title on its own line, clearly labeled +3. **Recommended Labels**: Show all suggested labels including size label (e.g., `feature`, `size/m`) + - Note: These are intelligent suggestions based on code analysis, but since GitHub CLI is unavailable, labels weren't fetched from the repository +4. **PR Description**: Show the complete markdown description ready to copy + +**Example output format:** +``` +GitHub CLI is not installed. You can install it with: brew install gh + +Alternatively, you can create the PR manually on GitHub: + +--- +PR Title: +[PLATFORM-7505] Add multi-category event filtering + +Recommended Labels (based on code analysis): +- feature +- size/m + +PR Description: + +--- + +Note: These labels are suggestions. Please verify they exist in your repository and apply them when creating the PR. +``` + +The generated content should follow the structure in `.github/PULL_REQUEST_TEMPLATE.md`. + +## PR Size Calculation + +The size label is determined by counting ONLY actual code changes, using `git diff` with appropriate filters. + +**Include in size calculation:** +- Swift files (*.swift) +- Configuration files (*.xcconfig, *.plist, etc.) +- Build files (Package.swift, project.pbxproj, etc.) +- Scripts (*.sh, *.rb, *.py, etc.) +- Any other source code files + +**Exclude from size calculation:** +- Image files (*.png, *.jpg, *.svg, *.pdf in asset catalogs) +- Documentation files (*.md) +- Asset catalogs (*.xcassets/*) image content +- Generated files +- Lock files (Package.resolved, Podfile.lock, etc.) + +**Implementation tip:** Use `git diff --numstat` and filter out binary files and documentation files to get accurate line counts. + +## Label Selection + +When GitHub CLI is available, fetch and intelligently select repository labels: + +### Fetching Labels +Use `gh label list` to retrieve all available labels with their descriptions. The output format includes: +- Label name +- Label description +- Label color + +### Selection Criteria +Analyze the PR changes and select labels based on: + +**1. Change Type:** +- Look for labels like: `feature`, `bugfix`, `enhancement`, etc. +- Infer from commit messages and changes + +**2. Status/Priority:** +- Look for labels like: `urgent`, `QA_passed`, `low_priority`, etc. +- Apply based on PR context + +**3. Size Label:** +- Always include the calculated size label: `size/xs`, `size/s`, `size/m`, `size/l`, or `size/xl` + +### Example Label Selection Logic +``` +Changed files: Fever/Features/Checkout/*.swift, FeverApp/Sources/Payment/*.swift +Commit messages: "Add Apple Pay support to checkout flow" + +Selected labels: +- feature (change type) +- size/m (calculated size: 450 lines) +``` + +### Applying Labels +When creating the PR with `gh pr create`, pass multiple labels using a comma-separated format **with no spaces around the commas**: +```bash +--label "feature,size/m" +``` + +## iOS-Specific Considerations + +When analyzing changes, pay special attention to: +- Swift version requirements +- iOS version compatibility +- New dependencies added to Package.swift +- UI changes requiring screenshots +- Accessibility considerations +- Performance implications +- New permissions required +- Dark mode compatibility +- Different device sizes (iPhone SE, standard, Plus/Max, iPad) diff --git a/.cursor/copilot-instructions.md b/.cursor/copilot-instructions.md new file mode 100644 index 0000000..4d09d0d --- /dev/null +++ b/.cursor/copilot-instructions.md @@ -0,0 +1,127 @@ +# GitHub Copilot PR Review Instructions + +When reviewing pull requests for this iOS project, please follow these guidelines: + +## 📚 Reference Rules Files + +Before reviewing, ensure you're familiar with these project-specific rules that MUST be followed: + +**Rules Directory**: `.feverrules/rules/` + +Cross-reference the PR against **ALL rules files** in this directory, which include: +- Commit message conventions and format requirements +- Pull request structure and required sections +- Model architecture and state management patterns +- Testing requirements and best practices +- Any other project-specific guidelines + +**Review Process**: Check the PR against every rule file in `.feverrules/rules/` to ensure complete compliance with all project standards. + +## 🚫 Files to Exclude from Review + +**NEVER review the following files:** +- `*.strings` files (e.g., `Localizable.strings`, `InfoPlist.strings`) + - These are localization files managed by the translation team + - Changes are automated and should not be reviewed by Copilot + +## Code Quality Standards + +### Swift Code Style +- Verify that code follows Swift naming conventions (camelCase for variables/functions, PascalCase for types) +- Check for proper use of access control modifiers (`private`, `fileprivate`, `internal`, `public`, `open`) +- Ensure optionals are handled safely (avoid force unwrapping `!` unless absolutely necessary) +- Look for proper error handling using `Result`, `throws`, or completion handlers +- Verify that async/await is used correctly for asynchronous operations +- Check for memory leaks (strong reference cycles, retain cycles in closures) + +### Architecture & Patterns +- Verify adherence to the project's architecture (MVVM, Coordinators, etc.) +- Check that models use `@Perceptible` macro (from swift-perception) instead of `@Observable` +- Ensure proper separation of concerns (ViewModels shouldn't contain UI code) +- Look for proper dependency injection patterns +- Verify that networking code is in appropriate repository/service layers + +### Testing +- Check if new features have corresponding unit tests +- Verify that tests are meaningful and not just for coverage +- Look for snapshot tests when UI changes are introduced +- Ensure mocks/stubs are used appropriately in tests + +### Performance & Best Practices +- Flag inefficient algorithms or unnecessary computations +- Check for proper use of lazy loading and pagination +- Look for potential memory leaks or retain cycles +- Verify that images are properly optimized and cached +- Check for proper handling of background/foreground transitions + +### iOS-Specific Concerns +- Verify minimum iOS version compatibility +- Check for proper use of SwiftUI vs UIKit (follow project conventions) +- Look for accessibility issues (missing labels, poor contrast, etc.) +- Verify proper handling of different screen sizes and orientations +- Check for proper use of iOS permissions (location, camera, notifications, etc.) + +## PR Structure Review + +### Required Sections +Verify that the PR includes: +1. **Context**: Ticket link and clear explanation of the problem and requirements +2. **Changes**: High-level list of what changed +3. **How to Test**: Step-by-step testing instructions with specific devices/configurations +4. **Screenshots/Videos**: Required for any visual changes (check the diff to determine if needed) + +### Optional but Recommended Sections +- **Questions**: Open questions or areas needing feedback +- **Trade-offs & Tech Debt**: Document shortcuts, alternative approaches, and known limitations + +### PR Title +- Must follow format: `[TICKET-ID] Description` +- Description should be clear and in imperative mood +- Example: `[PLATFORM-7505] Add multi-category event filtering` + +## Red Flags to Call Out + +### Critical Issues +- Force unwrapping optionals without justification +- Hardcoded credentials or API keys +- Disabled tests without explanation +- Missing error handling in critical paths +- Memory leaks or retain cycles +- Breaking changes without documentation + +### Code Smells +- Classes with too many responsibilities +- Duplicated code that should be refactored +- Magic numbers without constants +- Commented-out code without explanation +- TODO comments without ticket references + +### PR Issues +- Mixing refactoring with feature changes +- Unrelated changes included +- Missing testing instructions +- No description or context + +## Positive Feedback +Also highlight: +- Well-structured code with clear naming +- Comprehensive test coverage +- Good documentation and comments +- Thoughtful error handling +- Performance optimizations +- Accessibility improvements + +## Review Tone +- Be constructive and specific in feedback +- Suggest concrete improvements rather than just pointing out problems +- Acknowledge good practices when you see them +- Ask questions when something is unclear rather than assuming intent +- Prioritize feedback (critical vs. nice-to-have) + +## Project-Specific Context +- This is a production iOS app (Fever/LiveYourCity) +- Uses Swift Package Manager for dependencies +- Follows modern Swift patterns (async/await, Combine where appropriate) +- Uses swift-perception library for state management +- Has both UIKit and SwiftUI components +- Targets multiple iOS versions (check Base.xcconfig for minimum version) diff --git a/.cursor/rules/commit-guidelines.md b/.cursor/rules/commit-guidelines.md new file mode 100644 index 0000000..84fc14a --- /dev/null +++ b/.cursor/rules/commit-guidelines.md @@ -0,0 +1,111 @@ + + + + +# Commit Message Guidelines + +## Format + +``` +[] (): + + + +