20 KiB
20 KiB
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
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
echo "Phase 1/4: Analyzing commit style..."
./.scripts/style-analyzer.sh <count> <branch>
Phase 2: Pattern Detection
echo "Phase 2/4: Detecting conventions..."
./.scripts/pattern-detector.py --count <count> --branch <branch> --detailed
Phase 3: Scope Extraction
echo "Phase 3/4: Extracting scopes..."
./.scripts/scope-extractor.sh --count <count> --branch <branch> --min-frequency 2
Phase 4: Convention Recommendations
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:
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:
# 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
{
"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:
- All 4 analysis phases complete
- Results aggregated correctly
- Comprehensive profile generated
- Recommendations prioritized
- Style guide created
- Examples included
- Implementation guidance provided
- 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