mirror of
https://github.com/ivuorinen/nvm-auto-use.fish.git
synced 2026-02-24 14:54:31 +00:00
feat: refactor plugin architecture, enhance linting, CI & tooling
- Major refactor of core Fish functions for modularity, caching, and error handling - Improved `.editorconfig` and Makefile for stricter formatting and linting standards - Expanded linting support: added EditorConfig checks, auto-install for missing tools, and Makefile targets - Enhanced CI workflow with clearer permissions and job steps in GitHub Actions - Updated documentation in `README.md` and `CLAUDE.md` to reflect new features, advanced developer tools, and contribution guidelines - Improved Node.js version manager detection, switching, and installation logic - Added/updated utility functions for configuration, silent mode, notifications, and version extraction - Various bug fixes, code quality improvements, and expanded test coverage
This commit is contained in:
116
CLAUDE.md
116
CLAUDE.md
@@ -19,22 +19,34 @@ The plugin consists of two main Fish functions:
|
||||
|
||||
### Linting and Code Quality
|
||||
|
||||
The project uses a comprehensive linting setup with automatic tool installation:
|
||||
|
||||
```bash
|
||||
# Install all linting tools (markdownlint-cli, jsonlint, jq)
|
||||
# Install all linting tools (markdownlint-cli, jsonlint, jq, editorconfig-checker)
|
||||
make install-tools
|
||||
|
||||
# Run all linting checks
|
||||
# Run all linting checks (Fish, Markdown, JSON, EditorConfig)
|
||||
make lint
|
||||
|
||||
# Fix auto-fixable linting issues
|
||||
make lint-fix
|
||||
|
||||
# Individual linting commands
|
||||
make lint-fish # Lint Fish shell files
|
||||
make lint-markdown # Lint Markdown files
|
||||
make lint-json # Lint JSON files
|
||||
make lint-fish # Lint Fish shell files (formatting + syntax)
|
||||
make lint-markdown # Lint Markdown files (style, headers, lists)
|
||||
make lint-json # Lint JSON files (syntax validation)
|
||||
make lint-editorconfig # Check EditorConfig compliance (line endings, indentation)
|
||||
```
|
||||
|
||||
#### Supported Linting Tools
|
||||
|
||||
- **Fish shell**: `fish_indent` for formatting, `fish -n` for syntax validation
|
||||
- **Markdown**: `markdownlint-cli` with custom configuration (`.markdownlint.json`)
|
||||
- **JSON**: `jsonlint` or `jq` for syntax validation
|
||||
- **EditorConfig**: `editorconfig-checker` (auto-installed if missing)
|
||||
|
||||
The linting system automatically downloads missing tools and follows XDG standards for installation.
|
||||
|
||||
#### Manual Fish Commands
|
||||
|
||||
```fish
|
||||
@@ -48,14 +60,19 @@ find . -name "*.fish" -exec fish_indent --check {} \;
|
||||
fish -n functions/*.fish completions/*.fish
|
||||
```
|
||||
|
||||
### Installation/Testing
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Test plugin installation using Makefile
|
||||
make test
|
||||
# Run all tests (unit + integration)
|
||||
tests/test_runner.fish
|
||||
|
||||
# Test plugin installation in CI environment
|
||||
make test-ci
|
||||
# Run specific test types
|
||||
make test-unit # Unit tests only
|
||||
make test-integration # Integration tests only
|
||||
|
||||
# Test plugin installation
|
||||
make test # Local installation test
|
||||
make test-ci # CI environment test
|
||||
```
|
||||
|
||||
#### Manual Installation Commands
|
||||
@@ -86,6 +103,38 @@ nvm_auto_use_config debounce 1000
|
||||
nvm_auto_use_config exclude "build"
|
||||
```
|
||||
|
||||
### Developer Tools
|
||||
|
||||
```fish
|
||||
# Security and validation
|
||||
nvm_security check_version "18.17.0" # Validate version format and policies
|
||||
nvm_security audit # Comprehensive security audit
|
||||
nvm_security policy set min_version "16.0.0" # Set security policies
|
||||
|
||||
# Smart recommendations
|
||||
nvm_recommendations suggest_version new_project # Get version recommendations
|
||||
nvm_recommendations upgrade_path # Plan upgrade strategy
|
||||
nvm_recommendations security_update # Security-focused updates
|
||||
|
||||
# Diagnostics and debugging
|
||||
nvm_doctor check # Comprehensive health check
|
||||
nvm_doctor system # System information
|
||||
nvm_doctor managers # Check version managers
|
||||
nvm_doctor fix all # Auto-fix common issues
|
||||
|
||||
# Cache management
|
||||
nvm_cache stats # Cache statistics
|
||||
nvm_cache clear # Clear all cache
|
||||
nvm_cache get "key" # Get cached value
|
||||
|
||||
# Async operations
|
||||
nvm_async version_check "file" # Non-blocking version check
|
||||
nvm_async cleanup # Clean up background jobs
|
||||
|
||||
# Error recovery
|
||||
nvm_error_recovery manager_failure "nvm" "18.0.0" # Handle manager failures
|
||||
```
|
||||
|
||||
### Testing the Functions
|
||||
|
||||
```fish
|
||||
@@ -105,18 +154,59 @@ nvm_version_status
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
### Core Architecture
|
||||
|
||||
- The plugin hooks into Fish's variable change system using `--on-variable PWD`
|
||||
- Supports multiple Node.js version managers: nvm, fnm, volta, asdf
|
||||
- Supports multiple file formats: `.nvmrc`, `.node-version`, `.tool-versions`, `package.json` engines.node
|
||||
- Includes performance optimizations: caching, debouncing, directory exclusions
|
||||
- Configurable features: silent mode, auto-install toggle, notifications, project-only mode
|
||||
- Error handling includes checking if Node.js is available and graceful fallback when versions can't be switched
|
||||
- The search for version files traverses up the directory tree until it finds one or reaches the root directory
|
||||
|
||||
### Performance Features
|
||||
|
||||
- **XDG-compliant caching** with configurable TTL for version lookups and manager availability
|
||||
- **Async operations** for non-blocking version checks using Fish background jobs
|
||||
- **Debouncing** to prevent rapid version switching during directory navigation
|
||||
- **Smart directory exclusions** to skip unnecessary processing
|
||||
|
||||
### Security & Reliability
|
||||
|
||||
- **Version validation** with format checking and policy enforcement
|
||||
- **Security vulnerability scanning** with CVE checking (online and offline)
|
||||
- **Error recovery mechanisms** with graceful degradation and fallback strategies
|
||||
- **Input sanitization** to prevent injection attacks through version files
|
||||
|
||||
### Advanced Capabilities
|
||||
|
||||
- **Smart recommendations** for version selection, upgrades, and security updates
|
||||
- **Comprehensive diagnostics** with the `nvm_doctor` command for troubleshooting
|
||||
- **Extensive testing suite** with unit and integration tests
|
||||
- **Configuration management** with persistent settings and policy enforcement
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
### Fish Shell Code
|
||||
|
||||
- All Fish code must be formatted with `fish_indent` before committing
|
||||
- Functions should include description flags (`-d "description"`)
|
||||
- Use proper Fish conventions for variable scoping (`set -l`, `set -g`, `set -gx`)
|
||||
- Include comprehensive error handling and input validation
|
||||
- Follow Fish best practices for command substitution and string handling
|
||||
|
||||
### General Standards
|
||||
|
||||
- **Makefile**: 80-character line limit, tab indentation
|
||||
- **Markdown**: 120-character line limit, consistent heading structure
|
||||
- **JSON**: Valid syntax, proper formatting
|
||||
- **EditorConfig**: Consistent line endings (LF), final newlines, no trailing whitespace
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
- GitHub Actions automatically runs all linting checks on push/PR
|
||||
- All linting must pass before merging
|
||||
- Use `make test-ci` for testing plugin installation in CI environments
|
||||
|
||||
### Tool Installation
|
||||
|
||||
- Missing linting tools are automatically installed during `make install-tools`
|
||||
- Installation respects XDG standards: `$XDG_BIN_HOME` → `$HOME/bin` → `/usr/local/bin`
|
||||
- Uses secure temporary directories (`mktemp`) for downloads
|
||||
|
||||
Reference in New Issue
Block a user