587 lines
20 KiB
Markdown
587 lines
20 KiB
Markdown
# Operation: Learn Project
|
|
|
|
**Purpose:** Comprehensive project commit pattern learning - analyze all aspects of commit history to provide complete understanding of project conventions.
|
|
|
|
## Parameters
|
|
|
|
From `$ARGUMENTS` (after operation name):
|
|
- `count:N` - Number of commits to analyze (default: 100)
|
|
- `branch:name` - Branch to analyze (default: current branch)
|
|
- `format:json|text` - Output format (default: text)
|
|
- `save:path` - Save results to file (optional)
|
|
- `full:true|false` - Include detailed breakdown (default: false)
|
|
|
|
## Workflow
|
|
|
|
### 1. Validate Repository
|
|
|
|
```bash
|
|
if ! git rev-parse --git-dir >/dev/null 2>&1; then
|
|
echo "Error: Not in a git repository"
|
|
exit 1
|
|
fi
|
|
|
|
if ! git log -1 >/dev/null 2>&1; then
|
|
echo "Error: No commit history found"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
### 2. Execute Comprehensive Analysis
|
|
|
|
This operation orchestrates all other history-analysis operations for complete project learning:
|
|
|
|
**Phase 1: Style Analysis**
|
|
```bash
|
|
echo "Phase 1/4: Analyzing commit style..."
|
|
./.scripts/style-analyzer.sh <count> <branch>
|
|
```
|
|
|
|
**Phase 2: Pattern Detection**
|
|
```bash
|
|
echo "Phase 2/4: Detecting conventions..."
|
|
./.scripts/pattern-detector.py --count <count> --branch <branch> --detailed
|
|
```
|
|
|
|
**Phase 3: Scope Extraction**
|
|
```bash
|
|
echo "Phase 3/4: Extracting scopes..."
|
|
./.scripts/scope-extractor.sh --count <count> --branch <branch> --min-frequency 2
|
|
```
|
|
|
|
**Phase 4: Convention Recommendations**
|
|
```bash
|
|
echo "Phase 4/4: Generating recommendations..."
|
|
./.scripts/convention-recommender.py --count <count> --branch <branch> --priority all
|
|
```
|
|
|
|
### 3. Aggregate and Synthesize Results
|
|
|
|
Combine all analysis data into comprehensive project profile:
|
|
|
|
```python
|
|
project_profile = {
|
|
'metadata': {
|
|
'project_name': get_repo_name(),
|
|
'analysis_date': datetime.now(),
|
|
'commits_analyzed': count,
|
|
'branch': branch,
|
|
'first_commit_date': get_first_commit_date(),
|
|
'last_commit_date': get_last_commit_date()
|
|
},
|
|
'style': style_analysis_results,
|
|
'patterns': pattern_detection_results,
|
|
'scopes': scope_extraction_results,
|
|
'recommendations': convention_recommendations,
|
|
'confidence': calculate_confidence_score()
|
|
}
|
|
```
|
|
|
|
### 4. Generate Project Profile
|
|
|
|
**Output Structure:**
|
|
|
|
```
|
|
═══════════════════════════════════════════════════════════════
|
|
PROJECT COMMIT PROFILE
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Repository: git-commit-assistant
|
|
Branch: main
|
|
Analysis Date: 2024-03-10 14:30:00
|
|
Commits Analyzed: 100 (from 2024-01-01 to 2024-03-10)
|
|
|
|
Overall Consistency Score: 85/100 (GOOD)
|
|
Confidence Level: HIGH (100 commits analyzed)
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
📊 EXECUTIVE SUMMARY
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
✓ Project uses conventional commits consistently (87%)
|
|
✓ Strong imperative mood usage (92%)
|
|
✓ Good issue reference practice (67%)
|
|
○ Moderate body usage (34%)
|
|
○ Occasional breaking change documentation (8%)
|
|
|
|
Recommended Actions:
|
|
1. Maintain conventional commits format
|
|
2. Increase body usage for complex changes
|
|
3. Standardize breaking change documentation
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
📝 COMMIT STYLE ANALYSIS
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Format Distribution:
|
|
Conventional Commits: 87% ████████████████████████░░░
|
|
Simple Subject: 10% ███░░░░░░░░░░░░░░░░░░░░░░░
|
|
Other: 3% █░░░░░░░░░░░░░░░░░░░░░░░░░
|
|
|
|
Subject Lines:
|
|
Average Length: 47 characters (recommended: < 50)
|
|
Standard Dev: 8 characters
|
|
Exceeds 50 chars: 15% of commits
|
|
|
|
Length Distribution:
|
|
30-40 chars: ████████ (35%)
|
|
41-50 chars: ██████████ (42%)
|
|
51-60 chars: ████ (15%)
|
|
61+ chars: ██ (8%)
|
|
|
|
Body Usage:
|
|
Has Body: 34% of commits
|
|
Average Length: 120 characters
|
|
Bullet Points: 89% of bodies
|
|
Wrapping: 94% wrap at 72 chars
|
|
|
|
Footer Usage:
|
|
Issue References: 67% ████████████████████░░░░░
|
|
Breaking Changes: 8% ██░░░░░░░░░░░░░░░░░░░░░░
|
|
Co-Authors: 2% ░░░░░░░░░░░░░░░░░░░░░░░░
|
|
Signed-Off: 12% ███░░░░░░░░░░░░░░░░░░░░░
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
🎯 COMMIT TYPE ANALYSIS
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Type Distribution (from 87 conventional commits):
|
|
|
|
1. feat 35% ████████████████████ (30 commits)
|
|
└─ New features and capabilities
|
|
|
|
2. fix 30% ████████████████░ (26 commits)
|
|
└─ Bug fixes and corrections
|
|
|
|
3. docs 16% █████████░ (14 commits)
|
|
└─ Documentation updates
|
|
|
|
4. refactor 8% ████░ (7 commits)
|
|
└─ Code restructuring
|
|
|
|
5. test 5% ███░ (4 commits)
|
|
└─ Test additions/updates
|
|
|
|
6. chore 4% ██░ (3 commits)
|
|
└─ Maintenance tasks
|
|
|
|
7. perf 2% █░ (2 commits)
|
|
└─ Performance improvements
|
|
|
|
Type Usage Timeline (last 20 commits):
|
|
feat: ████████ (8 commits)
|
|
fix: ██████ (6 commits)
|
|
docs: ███ (3 commits)
|
|
refactor: ██ (2 commits)
|
|
chore: █ (1 commit)
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
🎨 SCOPE ANALYSIS
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Scopes Found: 15 unique
|
|
Scoped Commits: 88% (76/87 conventional commits)
|
|
|
|
Top Scopes by Frequency:
|
|
|
|
1. auth 23% ████████████████████ (20 commits)
|
|
Category: Authentication
|
|
Status: ACTIVE (used in last 10 commits)
|
|
Examples:
|
|
• feat(auth): implement OAuth2 authentication
|
|
• fix(auth): handle session timeout correctly
|
|
• refactor(auth): simplify middleware logic
|
|
|
|
2. api 19% ████████████████ (17 commits)
|
|
Category: Backend
|
|
Status: ACTIVE
|
|
Hierarchy: api/endpoints (7), api/middleware (5), api/validation (3)
|
|
|
|
3. ui 15% █████████████ (13 commits)
|
|
Category: Frontend
|
|
Status: ACTIVE
|
|
Hierarchy: ui/components (8), ui/styles (4)
|
|
|
|
4. db 12% ██████████ (10 commits)
|
|
Category: Database
|
|
Status: ACTIVE
|
|
|
|
5. docs 11% █████████ (9 commits)
|
|
Category: Documentation
|
|
Status: ACTIVE
|
|
|
|
6-15. (core, config, test, ci, deploy, utils, types, scripts, docker, nginx)
|
|
Combined: 20% (17 commits)
|
|
|
|
Scope Categories:
|
|
Features: 45% (auth, payment, search, notifications)
|
|
Backend: 32% (api, db, server, cache)
|
|
Frontend: 19% (ui, components, styles)
|
|
Infrastructure: 12% (ci, docker, deploy, nginx)
|
|
Documentation: 11% (docs, readme, changelog)
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
🔍 CONVENTION PATTERNS
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Writing Style:
|
|
Imperative Mood: 92% ██████████████████████░░
|
|
Capitalized Subject: 94% ██████████████████████░░
|
|
No Period at End: 88% ████████████████████░░░
|
|
Lowercase Scopes: 100% ████████████████████████
|
|
|
|
Message Structure:
|
|
Blank Line Before Body: 100% (all 34 bodies)
|
|
Body Wrapped at 72: 94% (32/34 bodies)
|
|
Bullet Points in Body: 89% (30/34 bodies)
|
|
Footer Separated: 100% (all 67 footers)
|
|
|
|
Issue References:
|
|
Format: "Closes #123" 45% ████████████
|
|
Format: "Fixes #456" 38% ██████████
|
|
Format: "Refs #789" 17% █████
|
|
|
|
Breaking Changes:
|
|
Format: "BREAKING CHANGE:" 100% (all 7 instances)
|
|
Always in footer: 100%
|
|
Includes description: 100%
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
💡 RECOMMENDATIONS (PRIORITIZED)
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
🔴 HIGH PRIORITY (Critical for Consistency)
|
|
|
|
1. ✓ Continue Using Conventional Commits
|
|
Current: 87% adoption
|
|
Target: Maintain 85%+
|
|
Impact: HIGH - Enables automation
|
|
|
|
2. ✓ Maintain Imperative Mood
|
|
Current: 92% compliance
|
|
Target: Maintain 90%+
|
|
Impact: HIGH - Readability and clarity
|
|
|
|
🟡 MEDIUM PRIORITY (Improve Quality)
|
|
|
|
3. ○ Increase Body Usage for Complex Changes
|
|
Current: 34% of commits
|
|
Target: 50% for multi-file changes
|
|
Impact: MEDIUM - Better documentation
|
|
|
|
When to add body:
|
|
• Changes affect >3 files
|
|
• Complex logic modifications
|
|
• Breaking changes
|
|
• Security-related changes
|
|
|
|
4. ○ Document Breaking Changes Consistently
|
|
Current: 8% when applicable
|
|
Target: 100% of breaking changes documented
|
|
Impact: MEDIUM - User experience
|
|
|
|
🟢 LOW PRIORITY (Polish)
|
|
|
|
5. ○ Consider Co-Author Attribution
|
|
Current: 2% usage
|
|
Target: Use for pair programming
|
|
Impact: LOW - Team recognition
|
|
|
|
6. ○ Add Signed-off-by for Compliance
|
|
Current: 12% usage
|
|
Target: If required by project policy
|
|
Impact: LOW - Legal compliance
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
📚 PROJECT-SPECIFIC STYLE GUIDE
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
COMMIT MESSAGE FORMAT
|
|
---------------------
|
|
<type>(<scope>): <subject> ← 50 chars max, imperative mood
|
|
|
|
<body> ← Optional, explain "why"
|
|
- Use bullet points ← Wrap at 72 characters
|
|
- Multiple lines OK
|
|
- Blank line before footer
|
|
|
|
<footer> ← Optional
|
|
BREAKING CHANGE: description
|
|
Closes #123
|
|
|
|
APPROVED TYPES (use these)
|
|
--------------------------
|
|
feat - New feature (35% of project commits)
|
|
fix - Bug fix (30% of project commits)
|
|
docs - Documentation (16% of project commits)
|
|
refactor - Code restructuring (8%)
|
|
test - Testing (5%)
|
|
chore - Maintenance (4%)
|
|
perf - Performance (2%)
|
|
|
|
STANDARD SCOPES (project-specific)
|
|
----------------------------------
|
|
auth - Authentication/authorization
|
|
api - Backend API endpoints
|
|
ui - User interface
|
|
db - Database operations
|
|
docs - Documentation
|
|
core - Core functionality
|
|
config - Configuration
|
|
test - Testing infrastructure
|
|
ci - CI/CD pipelines
|
|
deploy - Deployment
|
|
|
|
STYLE RULES
|
|
-----------
|
|
✓ Use imperative mood ("add" not "added")
|
|
✓ Capitalize first letter of subject
|
|
✓ No period at end of subject line
|
|
✓ Use lowercase for scopes
|
|
✓ Wrap body at 72 characters
|
|
✓ Separate body and footer with blank line
|
|
✓ Use bullet points in body (with - or •)
|
|
✓ Reference issues: "Closes #123", "Fixes #456"
|
|
✓ Document breaking changes in footer
|
|
|
|
REAL EXAMPLES FROM THIS PROJECT
|
|
--------------------------------
|
|
Example 1: Feature with body
|
|
feat(auth): implement OAuth2 authentication
|
|
|
|
- Add OAuth2 flow implementation
|
|
- Support Google and GitHub providers
|
|
- Include middleware for route protection
|
|
- Add configuration management
|
|
|
|
Closes #123
|
|
|
|
Example 2: Bug fix
|
|
fix(api): handle null pointer in user endpoint
|
|
|
|
The endpoint was not checking for null user objects
|
|
before accessing properties, causing crashes when
|
|
invalid user IDs were provided.
|
|
|
|
Fixes #456
|
|
|
|
Example 3: Breaking change
|
|
feat(api): change authentication flow
|
|
|
|
Update authentication to use OAuth2 tokens instead
|
|
of API keys for improved security.
|
|
|
|
BREAKING CHANGE: API now requires OAuth tokens
|
|
instead of API keys. Update all client applications
|
|
to use the new authentication flow.
|
|
|
|
Closes #789
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
🔧 IMPLEMENTATION GUIDE
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
1. SHARE WITH TEAM
|
|
• Add style guide to CONTRIBUTING.md
|
|
• Present in team meeting
|
|
• Add to onboarding docs
|
|
|
|
2. CONFIGURE GIT
|
|
Create .gitmessage template:
|
|
|
|
# <type>(<scope>): <subject>
|
|
#
|
|
# <body>
|
|
#
|
|
# <footer>
|
|
#
|
|
# Types: feat, fix, docs, refactor, test, chore, perf
|
|
# Scopes: auth, api, ui, db, docs, core, config
|
|
|
|
Then: git config commit.template .gitmessage
|
|
|
|
3. ADD PRE-COMMIT HOOKS
|
|
Install commitlint:
|
|
npm install --save-dev @commitlint/cli @commitlint/config-conventional
|
|
|
|
Configure commitlint.config.js:
|
|
module.exports = {
|
|
extends: ['@commitlint/config-conventional'],
|
|
rules: {
|
|
'scope-enum': [2, 'always', [
|
|
'auth', 'api', 'ui', 'db', 'docs', 'core',
|
|
'config', 'test', 'ci', 'deploy'
|
|
]]
|
|
}
|
|
};
|
|
|
|
4. ENABLE AUTOMATION
|
|
• Automated changelog: standard-version
|
|
• Semantic versioning: semantic-release
|
|
• Commit linting: commitlint + husky
|
|
|
|
5. MONITOR COMPLIANCE
|
|
Run this analysis monthly:
|
|
/history-analysis learn-project count:100
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
📈 CONFIDENCE ASSESSMENT
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Data Quality: ████████████████████████ HIGH
|
|
Sample Size: 100 commits ✓ Sufficient
|
|
Time Range: 70 days ✓ Representative
|
|
Consistency: 85/100 ✓ Good
|
|
Pattern Clarity: ████████████████████████ HIGH
|
|
|
|
Confidence Level: HIGH
|
|
|
|
This analysis is reliable for:
|
|
✓ Establishing project guidelines
|
|
✓ Onboarding new developers
|
|
✓ Configuring automation tools
|
|
✓ Team discussions and decisions
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
💾 SAVE OPTIONS
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
This analysis can be saved for reference:
|
|
/history-analysis learn-project save:docs/commit-conventions.md
|
|
|
|
Or export as JSON for tooling:
|
|
/history-analysis learn-project format:json save:commit-profile.json
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
Analysis Complete - Ready to Apply
|
|
═══════════════════════════════════════════════════════════════
|
|
```
|
|
|
|
### 5. Save to File (if requested)
|
|
|
|
If `save:path` parameter provided:
|
|
|
|
```bash
|
|
# Save text format
|
|
echo "$output" > "$save_path"
|
|
|
|
# Save JSON format
|
|
echo "$json_output" > "$save_path"
|
|
|
|
echo "✓ Analysis saved to: $save_path"
|
|
```
|
|
|
|
### 6. JSON Output Structure
|
|
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"project_name": "git-commit-assistant",
|
|
"analysis_date": "2024-03-10T14:30:00Z",
|
|
"commits_analyzed": 100,
|
|
"branch": "main",
|
|
"date_range": {
|
|
"first_commit": "2024-01-01",
|
|
"last_commit": "2024-03-10"
|
|
}
|
|
},
|
|
"scores": {
|
|
"overall_consistency": 85,
|
|
"style_consistency": 87,
|
|
"pattern_consistency": 92,
|
|
"content_consistency": 67,
|
|
"confidence": "high"
|
|
},
|
|
"style_analysis": {
|
|
"conventional_commits_percentage": 87,
|
|
"average_subject_length": 47,
|
|
"body_usage_percentage": 34,
|
|
"footer_usage_percentage": 67
|
|
},
|
|
"types": [...],
|
|
"scopes": [...],
|
|
"patterns": {...},
|
|
"recommendations": {
|
|
"high_priority": [...],
|
|
"medium_priority": [...],
|
|
"low_priority": [...]
|
|
},
|
|
"style_guide": {
|
|
"format": "<type>(<scope>): <subject>",
|
|
"types": [...],
|
|
"scopes": [...],
|
|
"rules": [...]
|
|
},
|
|
"examples": [...],
|
|
"automation": {
|
|
"commitlint_config": {...},
|
|
"changelog_generator": "standard-version",
|
|
"semantic_release": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
**No git repository:**
|
|
- Error: "Not in a git repository"
|
|
- Guidance: Run from within git project directory
|
|
|
|
**Insufficient commits:**
|
|
- Warning: "Only X commits available (recommended: 50+)"
|
|
- Adjust: Analyze all available commits
|
|
- Note: Lower confidence level
|
|
|
|
**Analysis failure:**
|
|
- Partial results: Return what was successfully analyzed
|
|
- Error details: Indicate which phase failed
|
|
- Retry: Suggest re-running with different parameters
|
|
|
|
## Integration Usage
|
|
|
|
**New project setup:**
|
|
```
|
|
Developer: "What are the commit conventions?"
|
|
→ Run: /history-analysis learn-project
|
|
→ Get: Complete style guide
|
|
→ Configure: Git template and hooks
|
|
```
|
|
|
|
**Team standardization:**
|
|
```
|
|
Lead: "Let's review our commit practices"
|
|
→ Run: /history-analysis learn-project save:docs/conventions.md
|
|
→ Review: Recommendations with team
|
|
→ Implement: Top priorities
|
|
→ Document: In CONTRIBUTING.md
|
|
```
|
|
|
|
**Automation setup:**
|
|
```
|
|
DevOps: "Configure commit validation"
|
|
→ Run: /history-analysis learn-project format:json
|
|
→ Extract: Approved types and scopes
|
|
→ Configure: commitlint with project rules
|
|
→ Deploy: Pre-commit hooks
|
|
```
|
|
|
|
## Success Criteria
|
|
|
|
Operation succeeds when:
|
|
- [x] All 4 analysis phases complete
|
|
- [x] Results aggregated correctly
|
|
- [x] Comprehensive profile generated
|
|
- [x] Recommendations prioritized
|
|
- [x] Style guide created
|
|
- [x] Examples included
|
|
- [x] Implementation guidance provided
|
|
- [x] Confidence level assessed
|
|
|
|
## Performance
|
|
|
|
- **Phase 1 (Style):** ~2 seconds
|
|
- **Phase 2 (Patterns):** ~3 seconds
|
|
- **Phase 3 (Scopes):** ~2 seconds
|
|
- **Phase 4 (Recommendations):** ~1 second
|
|
- **Total:** ~8-10 seconds for 100 commits
|