# Operation: Extract Scopes **Purpose:** Discover and analyze commonly used scopes in commit messages to understand project structure and component organization. ## Parameters From `$ARGUMENTS` (after operation name): - `count:N` - Number of commits to analyze (default: 50) - `branch:name` - Branch to analyze (default: current branch) - `format:json|text` - Output format (default: text) - `min_frequency:N` - Minimum occurrences to include (default: 2) - `top:N` - Show only top N scopes (default: 20) ## Workflow ### 1. Validate Repository ```bash # Check git repository if ! git rev-parse --git-dir >/dev/null 2>&1; then echo "Error: Not in a git repository" exit 1 fi ``` ### 2. Execute Scope Extraction Invoke the scope-extractor.sh utility script: ```bash ./.scripts/scope-extractor.sh --count --branch --min-frequency ``` The script will: - Parse commit messages - Extract scopes using regex patterns - Count scope frequencies - Analyze scope naming patterns - Categorize scopes by type ### 3. Scope Extraction Algorithm **Pattern Matching:** ```bash # Primary pattern: type(scope): subject ^[a-z]+\(([^)]+)\): # Examples: feat(auth): add OAuth → scope: "auth" fix(api/users): handle null → scope: "api/users" docs(readme): update guide → scope: "readme" ``` **Nested Scope Handling:** ```bash # Hierarchical scopes api/endpoints → parent: "api", child: "endpoints" ui/components → parent: "ui", child: "components" core/auth → parent: "core", child: "auth" ``` **Multi-Scope Handling:** ```bash # Comma-separated scopes feat(api,docs): add endpoint → scopes: ["api", "docs"] fix(ui, ux): button alignment → scopes: ["ui", "ux"] ``` ### 4. Scope Analysis Categories **A. Frequency Analysis** ```json { "scope": "auth", "count": 23, "percentage": 18.1, "first_seen": "2024-01-15", "last_seen": "2024-03-10", "active": true } ``` **B. Scope Hierarchy** ```json { "api": { "count": 45, "children": { "endpoints": 12, "middleware": 8, "validation": 6 } } } ``` **C. Scope Categories** ``` Architecture: core, utils, config Features: auth, payment, search UI: ui, components, styles Backend: api, db, server Infrastructure: ci, docker, deploy Documentation: docs, readme, changelog Testing: test, e2e, unit ``` ### 5. Output Structure **Text Format (default):** ``` Scope Extraction Analysis ========================= Commits Analyzed: 50 Branch: main Scopes Found: 15 unique Total Scoped Commits: 44/50 (88%) TOP SCOPES BY FREQUENCY ----------------------- 1. auth 23 (18.1%) ████████████████████ └─ Authentication and authorization 2. api 19 (14.9%) ████████████████ ├─ endpoints 7 ├─ middleware 5 └─ validation 3 3. ui 15 (11.8%) █████████████ ├─ components 8 └─ styles 4 4. db 12 (9.4%) ██████████ └─ Database operations 5. docs 11 (8.7%) █████████ └─ Documentation 6. core 8 (6.3%) ███████ └─ Core functionality 7. config 7 (5.5%) ██████ └─ Configuration 8. test 6 (4.7%) █████ └─ Testing 9. ci 5 (3.9%) ████ └─ CI/CD pipelines 10. deploy 4 (3.1%) ███ └─ Deployment SCOPE CATEGORIES ---------------- Features (45%): auth, payment, search Backend (32%): api, db, server UI (19%): ui, components, styles Infrastructure (12%): ci, docker, deploy Documentation (8%): docs, readme SCOPE PATTERNS -------------- Naming Style: lowercase, hyphen-separated Hierarchy: Uses / for nested scopes (api/endpoints) Multi-Scope: Occasional (3% of commits) Active Scopes: 12/15 (used in last 10 commits) Deprecated: payment-v1, legacy-api RECOMMENDATIONS --------------- • Use 'auth' for authentication/authorization changes • Use 'api' for backend API modifications • Use 'ui' for user interface changes • Consider hierarchical scopes for complex modules (api/endpoints) • Active scopes: auth, api, ui, db, docs, core, config • Avoid deprecated: payment-v1, legacy-api RECENT SCOPE USAGE (last 10 commits) ------------------------------------ auth ████ (4 commits) api ███ (3 commits) ui ██ (2 commits) docs █ (1 commit) ``` **JSON Format:** ```json { "analysis_type": "scope_extraction", "commits_analyzed": 50, "branch": "main", "statistics": { "total_scopes": 15, "scoped_commits": 44, "scoped_percentage": 88, "active_scopes": 12, "deprecated_scopes": 2 }, "scopes": [ { "name": "auth", "count": 23, "percentage": 18.1, "category": "feature", "description": "Authentication and authorization", "hierarchy": null, "first_seen": "2024-01-15", "last_seen": "2024-03-10", "active": true, "recent_usage": 4, "examples": [ "feat(auth): implement OAuth2", "fix(auth): session timeout", "refactor(auth): simplify middleware" ] }, { "name": "api", "count": 19, "percentage": 14.9, "category": "backend", "description": "API endpoints and logic", "hierarchy": { "endpoints": 7, "middleware": 5, "validation": 3 }, "active": true, "recent_usage": 3 } ], "categories": { "feature": {"count": 45, "percentage": 45}, "backend": {"count": 32, "percentage": 32}, "ui": {"count": 19, "percentage": 19} }, "patterns": { "naming_style": "lowercase_hyphen", "uses_hierarchy": true, "uses_multi_scope": true, "multi_scope_percentage": 3 }, "recommendations": [ "Use 'auth' for authentication/authorization changes", "Use 'api' for backend API modifications", "Consider hierarchical scopes for complex modules" ] } ``` ### 6. Scope Categorization Logic **Category Detection:** ```python def categorize_scope(scope_name, usage_patterns): """Categorize scope based on name and usage""" # Authentication/Authorization if scope_name in ['auth', 'security', 'login', 'oauth']: return 'feature', 'Authentication' # API/Backend if scope_name in ['api', 'endpoint', 'backend', 'server']: return 'backend', 'API and backend' # UI/Frontend if scope_name in ['ui', 'component', 'style', 'frontend']: return 'ui', 'User interface' # Database if scope_name in ['db', 'database', 'schema', 'migration']: return 'backend', 'Database' # Infrastructure if scope_name in ['ci', 'cd', 'deploy', 'docker', 'k8s']: return 'infrastructure', 'Infrastructure' # Documentation if scope_name in ['docs', 'readme', 'changelog']: return 'documentation', 'Documentation' # Testing if scope_name in ['test', 'e2e', 'unit', 'integration']: return 'testing', 'Testing' # Default return 'other', 'Other' ``` ### 7. Trend Analysis **Activity Tracking:** ``` Scope Activity Timeline (last 30 days): auth: ████████████████ (very active) api: ████████████ (active) ui: ████████ (moderate) db: ████ (low) test: ██ (occasional) docs: █ (rare) ``` **Deprecated Scope Detection:** ```python def is_deprecated(scope): """Detect if scope is deprecated""" # Not used in last 20 commits if scope.last_seen_commit_index > 20: return True # Explicitly marked as deprecated if 'legacy' in scope.name or 'v1' in scope.name: return True return False ``` ## Error Handling **No scopes found:** - Warning: "No scopes detected in commit history" - Suggestion: "Project may not use conventional commits format" - Return: Empty scope list with explanation **Minimal scopes:** - Warning: "Only X scopes found with min_frequency threshold" - Suggestion: "Lower min_frequency or analyze more commits" **Malformed scopes:** - Skip invalid entries - Log: "Skipped N malformed scope entries" - Continue with valid scopes ## Integration Usage **By commit-assistant agent:** ``` User modifies auth files: → Invoke: /history-analysis extract-scopes → Find: 'auth' is common scope (18.1%) → Suggest: Use 'auth' scope for this commit ``` **By message-generation skill:** ``` Generating commit message: → Extract scopes from history → Check if current files match known scopes → Auto-suggest appropriate scope ``` **By identify-scope operation:** ``` Unknown scope needed: → Check extracted scopes → Find similar/related scopes → Recommend best match ``` ## Success Criteria Operation succeeds when: - [x] All scopes extracted from commits - [x] Frequencies calculated correctly - [x] Hierarchies identified - [x] Categories assigned accurately - [x] Active/deprecated status determined - [x] Recommendations generated - [x] Output formatted properly ## Performance - **Extraction Time:** ~1-2 seconds for 50 commits - **Regex Matching:** ~0.02ms per commit - **Memory:** Low (scope hash table only)