384 lines
10 KiB
Markdown
384 lines
10 KiB
Markdown
# clj-kondo Skill - Index
|
|
|
|
Welcome to the comprehensive clj-kondo skill! Master Clojure linting, from basic usage to writing custom hooks for domain-specific rules.
|
|
|
|
## 📚 Documentation Files
|
|
|
|
### 1. [README.md](README.md) - Getting Started
|
|
**Size:** ~8KB | **Reading time:** 10-15 minutes
|
|
|
|
Quick overview including:
|
|
- What is clj-kondo?
|
|
- Installation
|
|
- Basic usage examples
|
|
- First hook example
|
|
- What the skill covers
|
|
- Learning path
|
|
|
|
**Start here** if you're new to clj-kondo.
|
|
|
|
### 2. [SKILL.md](SKILL.md) - Complete Guide
|
|
**Size:** ~35KB | **Reading time:** 45-60 minutes
|
|
|
|
Comprehensive documentation covering:
|
|
- Introduction and installation
|
|
- Getting started and basic usage
|
|
- Configuration management
|
|
- Built-in linters reference
|
|
- **Custom hooks development** (extensive section)
|
|
- Hook API reference
|
|
- Practical hook examples
|
|
- IDE integration
|
|
- CI/CD integration
|
|
- Best practices
|
|
- Troubleshooting
|
|
|
|
**Start here** for comprehensive learning or reference.
|
|
|
|
### 3. [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Cheat Sheet
|
|
**Size:** ~7KB | **Quick lookup**
|
|
|
|
Concise reference with:
|
|
- Command-line usage
|
|
- Common configurations
|
|
- Linter settings
|
|
- Hook patterns
|
|
- IDE integration snippets
|
|
- CI/CD templates
|
|
- Troubleshooting tips
|
|
|
|
**Use this** when you need quick reference.
|
|
|
|
### 4. [examples.clj](examples.clj) - Hook Examples
|
|
**Size:** ~8KB | **Executable script**
|
|
|
|
8 practical hook examples:
|
|
1. Basic deprecation warning
|
|
2. Argument count validation
|
|
3. Argument type validation
|
|
4. Required map keys validation
|
|
5. Macro expansion for DSL
|
|
6. Route definition expansion
|
|
7. Thread-safety hints
|
|
8. Team convention enforcement
|
|
|
|
Plus complete hook file template.
|
|
|
|
**Run this** to see hook patterns:
|
|
```bash
|
|
bb examples.clj
|
|
```
|
|
|
|
### 5. [metadata.edn](metadata.edn) - Skill Metadata
|
|
**Size:** ~4KB | **Machine-readable**
|
|
|
|
Structured information about:
|
|
- Skill properties and versioning
|
|
- Library information
|
|
- Use cases and features
|
|
- Learning path
|
|
- Platform support
|
|
|
|
## 🎯 Quick Navigation
|
|
|
|
### By Experience Level
|
|
|
|
**Beginner** (Never used clj-kondo)
|
|
1. Read [README.md](README.md) for overview
|
|
2. Install clj-kondo
|
|
3. Run basic linting on your code
|
|
4. Review "Getting Started" in [SKILL.md](SKILL.md)
|
|
5. Understand built-in linters
|
|
|
|
**Intermediate** (Used clj-kondo, want customization)
|
|
1. Read "Configuration" in [SKILL.md](SKILL.md)
|
|
2. Study "Built-in Linters" section
|
|
3. Customize for your project
|
|
4. Set up IDE integration
|
|
5. Add to CI/CD pipeline
|
|
|
|
**Advanced** (Ready to write hooks)
|
|
1. Read "Custom Hooks" in [SKILL.md](SKILL.md)
|
|
2. Run [examples.clj](examples.clj) to see patterns
|
|
3. Study Hook API reference
|
|
4. Write your first deprecation hook
|
|
5. Progress to complex validation hooks
|
|
6. Learn macro expansion hooks
|
|
|
|
### By Task
|
|
|
|
**Need to install and start using clj-kondo?**
|
|
- README.md → "Quick Start"
|
|
- SKILL.md → "Installation" and "Getting Started"
|
|
|
|
**Need to configure linters?**
|
|
- SKILL.md → "Configuration"
|
|
- QUICK_REFERENCE.md → "Basic Configuration" and "Common Linter Configurations"
|
|
|
|
**Want to understand what clj-kondo checks?**
|
|
- SKILL.md → "Built-in Linters"
|
|
- QUICK_REFERENCE.md → "Common Linter Configurations"
|
|
|
|
**Need to write a deprecation warning hook?**
|
|
- SKILL.md → "Custom Hooks" → "Creating Your First Hook"
|
|
- examples.clj → Example 1 (Deprecation Warning)
|
|
- QUICK_REFERENCE.md → "Common Hook Patterns" → "Deprecation Warning"
|
|
|
|
**Need to validate function arguments?**
|
|
- SKILL.md → "Custom Hooks" → "Practical Hook Examples"
|
|
- examples.clj → Examples 2-4 (Argument validation)
|
|
- QUICK_REFERENCE.md → "Common Hook Patterns"
|
|
|
|
**Need to support a custom DSL/macro?**
|
|
- SKILL.md → "Custom Hooks" → ":macroexpand Hooks"
|
|
- examples.clj → Examples 5-6 (Macro expansion)
|
|
- QUICK_REFERENCE.md → "macroexpand Hook"
|
|
|
|
**Need to integrate with IDE?**
|
|
- SKILL.md → "IDE Integration"
|
|
- QUICK_REFERENCE.md → "IDE Integration"
|
|
|
|
**Need to add to CI/CD?**
|
|
- SKILL.md → "CI/CD Integration"
|
|
- QUICK_REFERENCE.md → "CI/CD Patterns"
|
|
|
|
## 🚀 Suggested Learning Paths
|
|
|
|
### Path 1: Basic User (2-3 hours)
|
|
|
|
**Goal:** Use clj-kondo effectively for your projects
|
|
|
|
1. ✅ **Read README.md** (10 min)
|
|
- Understand what clj-kondo does
|
|
- See quick examples
|
|
|
|
2. ✅ **Install and test** (15 min)
|
|
- Install clj-kondo
|
|
- Run on your codebase
|
|
- Review findings
|
|
|
|
3. ✅ **Study SKILL.md: Getting Started** (20 min)
|
|
- Command-line usage
|
|
- Output formats
|
|
- Basic workflow
|
|
|
|
4. ✅ **Study SKILL.md: Configuration** (30 min)
|
|
- Configuration file structure
|
|
- Linter levels
|
|
- Inline suppressions
|
|
|
|
5. ✅ **Study SKILL.md: Built-in Linters** (30 min)
|
|
- Understand what's checked
|
|
- Configure for your needs
|
|
|
|
6. ✅ **Integrate with IDE** (20 min)
|
|
- Set up editor integration
|
|
- Test real-time linting
|
|
|
|
7. ✅ **Practice** (30 min)
|
|
- Configure for your project
|
|
- Fix some linting issues
|
|
- Customize linter levels
|
|
|
|
### Path 2: Hook Developer (6-8 hours)
|
|
|
|
**Goal:** Write custom hooks for domain-specific linting
|
|
|
|
**Prerequisites:** Complete Basic User path
|
|
|
|
1. ✅ **Study SKILL.md: Custom Hooks intro** (45 min)
|
|
- What are hooks
|
|
- When to use hooks
|
|
- Hook architecture
|
|
|
|
2. ✅ **Run examples.clj** (15 min)
|
|
- See hook patterns in action
|
|
- Understand hook structure
|
|
|
|
3. ✅ **Study SKILL.md: Hook API Reference** (45 min)
|
|
- Node functions
|
|
- Node constructors
|
|
- Return values
|
|
|
|
4. ✅ **Write first hook: Deprecation** (60 min)
|
|
- Create hook file
|
|
- Register in config
|
|
- Test it
|
|
|
|
5. ✅ **Study examples.clj in detail** (60 min)
|
|
- Analyze each example
|
|
- Understand patterns
|
|
- Note code structure
|
|
|
|
6. ✅ **Write validation hooks** (90 min)
|
|
- Argument count validation
|
|
- Argument type validation
|
|
- Map keys validation
|
|
|
|
7. ✅ **Study macroexpand hooks** (60 min)
|
|
- SKILL.md → ":macroexpand Hooks"
|
|
- examples.clj → Examples 5-6
|
|
- Understand node transformation
|
|
|
|
8. ✅ **Write DSL expansion hook** (90 min)
|
|
- For your own macros
|
|
- Test thoroughly
|
|
- Document usage
|
|
|
|
9. ✅ **Study SKILL.md: Testing and Distribution** (30 min)
|
|
- Testing strategies
|
|
- Distribution patterns
|
|
|
|
10. ✅ **Practice** (90 min)
|
|
- Write hooks for your codebase
|
|
- Test edge cases
|
|
- Document hooks
|
|
|
|
### Path 3: Team Lead (4-5 hours)
|
|
|
|
**Goal:** Set up clj-kondo for team with custom rules
|
|
|
|
**Prerequisites:** Complete Basic User path
|
|
|
|
1. ✅ **Study SKILL.md: Configuration** (deep dive) (45 min)
|
|
- Team configuration strategies
|
|
- Consistent aliases
|
|
- Convention enforcement
|
|
|
|
2. ✅ **Set up team configuration** (60 min)
|
|
- Define team standards
|
|
- Configure linters
|
|
- Document choices
|
|
|
|
3. ✅ **Study custom hooks** (90 min)
|
|
- SKILL.md → "Custom Hooks"
|
|
- examples.clj → All examples
|
|
- Identify team needs
|
|
|
|
4. ✅ **Write team convention hooks** (90 min)
|
|
- Naming conventions
|
|
- API usage rules
|
|
- Deprecation warnings
|
|
|
|
5. ✅ **Set up CI/CD** (45 min)
|
|
- SKILL.md → "CI/CD Integration"
|
|
- Add to your pipeline
|
|
- Configure failure thresholds
|
|
|
|
6. ✅ **Documentation** (30 min)
|
|
- Document configuration
|
|
- Document custom hooks
|
|
- Create team guide
|
|
|
|
## 📊 Skill Coverage
|
|
|
|
This skill covers **100%** of clj-kondo's core functionality:
|
|
|
|
### Basic Usage
|
|
- ✅ Installation (all platforms)
|
|
- ✅ Command-line usage
|
|
- ✅ Output formats
|
|
- ✅ Cache management
|
|
|
|
### Configuration
|
|
- ✅ Configuration file structure
|
|
- ✅ Linter levels
|
|
- ✅ Global and local config
|
|
- ✅ Inline suppressions
|
|
- ✅ Configuration merging
|
|
|
|
### Built-in Linters
|
|
- ✅ Namespace linters
|
|
- ✅ Binding linters
|
|
- ✅ Function/arity linters
|
|
- ✅ Collection linters
|
|
- ✅ Type checking
|
|
|
|
### Custom Hooks (Advanced)
|
|
- ✅ Hook architecture
|
|
- ✅ `:analyze-call` hooks
|
|
- ✅ `:macroexpand` hooks
|
|
- ✅ Hook API reference
|
|
- ✅ 8+ practical examples
|
|
- ✅ Testing strategies
|
|
- ✅ Distribution patterns
|
|
|
|
### Integration
|
|
- ✅ VS Code (Calva)
|
|
- ✅ Emacs
|
|
- ✅ IntelliJ/Cursive
|
|
- ✅ Vim/Neovim
|
|
- ✅ GitHub Actions
|
|
- ✅ GitLab CI
|
|
- ✅ Pre-commit hooks
|
|
|
|
## 🎓 What You'll Learn
|
|
|
|
After completing this skill:
|
|
|
|
**Basic Level:**
|
|
- ✅ Install and run clj-kondo
|
|
- ✅ Understand linting output
|
|
- ✅ Configure linters for your project
|
|
- ✅ Suppress warnings appropriately
|
|
- ✅ Integrate with IDE
|
|
- ✅ Add to CI/CD pipeline
|
|
|
|
**Advanced Level:**
|
|
- ✅ Write deprecation warning hooks
|
|
- ✅ Validate function arguments
|
|
- ✅ Check required map keys
|
|
- ✅ Expand custom macros for analysis
|
|
- ✅ Enforce team conventions
|
|
- ✅ Test hooks effectively
|
|
- ✅ Distribute hooks with libraries
|
|
|
|
## 💡 Use Cases Covered
|
|
|
|
1. **Basic Linting** - Catch syntax errors and common mistakes
|
|
2. **Code Quality** - Enforce best practices
|
|
3. **API Deprecation** - Warn about deprecated functions
|
|
4. **Argument Validation** - Check function arguments
|
|
5. **DSL Support** - Analyze custom macros
|
|
6. **Team Conventions** - Enforce naming and style rules
|
|
7. **Domain Rules** - Validate business logic
|
|
8. **CI/CD Integration** - Automated quality checks
|
|
|
|
## 🔗 External Resources
|
|
|
|
- [Official GitHub Repository](https://github.com/clj-kondo/clj-kondo)
|
|
- [Configuration Reference](https://github.com/clj-kondo/clj-kondo/blob/master/doc/config.md)
|
|
- [Hooks API Documentation](https://github.com/clj-kondo/clj-kondo/blob/master/doc/hooks.md)
|
|
- [Linters Reference](https://github.com/clj-kondo/clj-kondo/blob/master/doc/linters.md)
|
|
- [Hook Examples Repository](https://github.com/clj-kondo/clj-kondo/tree/master/examples)
|
|
|
|
## 📝 Version Information
|
|
|
|
- **Skill Version:** 1.0.0
|
|
- **clj-kondo Version:** 2024.11.14
|
|
- **Created:** 2025-11-10
|
|
- **Language:** Clojure
|
|
- **Platform:** Cross-platform (Linux, macOS, Windows)
|
|
- **License:** EPL-1.0
|
|
|
|
## 🎯 Next Steps
|
|
|
|
### If you're new to clj-kondo:
|
|
1. Start with [README.md](README.md)
|
|
2. Follow "Path 1: Basic User"
|
|
3. Practice on your projects
|
|
|
|
### If you want to write hooks:
|
|
1. Complete Basic User path first
|
|
2. Read [SKILL.md](SKILL.md) "Custom Hooks" section
|
|
3. Run [examples.clj](examples.clj)
|
|
4. Follow "Path 2: Hook Developer"
|
|
|
|
### If you need quick reference:
|
|
1. Use [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
|
|
2. Bookmark for fast lookups
|
|
|
|
---
|
|
|
|
**Ready to start?** Begin with [README.md](README.md) for an introduction, or jump to [SKILL.md](SKILL.md) for comprehensive coverage!
|