smartchok/readme.plan.md

Migration Plan: smartchok to Chokidar 4.x

Command to reread CLAUDE.md: cat /home/philkunz/.claude/CLAUDE.md

MIGRATION COMPLETED ✅

All phases of the migration have been successfully completed:

Current State Analysis

• Current dependency: @tempfix/watcher v2.3.0 (a fork of fabiospampinato/watcher)
• Target: Chokidar v4.0.3
• Major challenge: Chokidar 4.x removed glob support, but smartchok heavily uses glob patterns

Migration Plan

Phase 1: Preparation

1. Install chokidar 4.x and glob library for pattern matching
   • pnpm install chokidar@^4.0.3
   • pnpm install picomatch (for glob pattern matching)
   • pnpm uninstall @tempfix/watcher

Phase 2: Code Changes

2.1 Update Plugin Imports (ts/smartchok.plugins.ts)

• Remove @tempfix/watcher import
• Add chokidar import
• Add picomatch for glob pattern matching

2.2 Update Smartchok Class (ts/smartchok.classes.smartchok.ts)

• Replace watcher initialization with chokidar
• Implement custom glob filtering using picomatch
• Update event mapping to match chokidar's event names
• Adjust watcher options to match chokidar's API

2.3 Handle Glob Patterns

Since chokidar 4.x removed glob support, we need to:

• Parse glob patterns to extract base directories
• Use chokidar to watch base directories
• Use picomatch to filter events based on glob patterns
• Ensure backward compatibility with existing API

2.4 Event Mapping

Map chokidar events to existing smartchok events:

• Keep existing event names for backward compatibility
• Ensure all current functionality is preserved

Phase 3: Testing

1. Run existing tests to ensure backward compatibility
2. Add new tests for glob pattern handling
3. Test edge cases with complex glob patterns
4. Verify performance with large file sets

Phase 4: Documentation

1. Update readme.md to reflect the change to chokidar 4.x
2. Document any API changes (if any)
3. Update version number in package.json

Technical Details

Key Differences to Handle:

1. Glob Support: Implement custom glob filtering layer
2. API Changes: Adapt initialization and option passing
3. Event Names: Map between different event naming conventions
4. Minimum Node Version: Ensure compatibility with Node 14+

Risk Mitigation:

• Maintain backward compatibility with existing API
• Extensive testing with current test suite
• Consider keeping a legacy branch if breaking changes are unavoidable