svgop Improvement Plan

Executive Summary

svgop is a valuable tool that provides standalone SVG optimization without requiring Node.js. However, the project has accumulated technical debt and needs modernization. This plan outlines a comprehensive approach to improve stability, elegance, and deployability while maintaining the core value proposition of a small, efficient binary.

1. Dependency Modernization

1.1 Update svgo Library

The current svgo version (1.3.2) is severely outdated. The latest version (3.x) includes significant improvements:

Strategy:

1. Audit breaking changes between svgo 1.3.2 and 3.x
2. Update the patch/config.js approach to work with new svgo architecture
3. Consider using svgo's new plugin system instead of patching config.js
4. Test thoroughly to ensure optimization results remain consistent

Challenges:

• svgo 3.x has a completely different configuration system
• Plugin API has changed significantly
• May require rewriting the wrapper logic

1.2 Update Build Dependencies

webpack 4 → webpack 5:

• Better tree shaking for smaller bundles
• Native support for ES modules
• Improved build performance

Other dependencies:

• Update get-stdin to latest version
• Update all dev dependencies for security patches

2. Build System Improvements

2.1 Fix Docker Build Issues

The Docker build is currently broken. We need to:

1. Debug the build-with-docker.sh script

   • Identify why builds are failing
   • Update Docker base images to newer versions
   • Ensure all build dependencies are properly installed

2. Modernize Docker setup

   • Use multi-stage builds for smaller images
   • Add GitHub Actions for automated Docker builds
   • Create separate Dockerfiles for different targets

2.2 Expand QuickJS Platform Support

Currently only macOS QuickJS builds are provided. We should:

1. Create Linux QuickJS builds

   • Set up cross-compilation or native Linux build environment
   • Test on major distributions (Ubuntu, Debian, Alpine)
   • Provide both x64 and ARM64 builds

2. Create Windows QuickJS builds

   • Set up MinGW or MSVC build environment
   • Handle Windows-specific path and I/O issues
   • Test on Windows 10/11

3. Automate QuickJS builds

   • Use GitHub Actions for all platforms
   • Create build matrix for different OS/arch combinations
   • Automate binary signing for macOS/Windows

2.3 Improve Build Architecture

1. Eliminate manual patching

   • Create a proper abstraction layer instead of patching svgo files
   • Use dependency injection or configuration overrides
   • Make the build process more maintainable

2. Modularize build scripts

   • Split Makefile into platform-specific components
   • Create shared build utilities
   • Add proper error handling and logging

3. Feature Enhancements

3.1 Add Command-Line Options

The current tool has no CLI options. We should add:

1. Basic options:

   • --help / -h: Show usage information
   • --version / -v: Show version
   • --output / -o: Specify output file (alternative to stdout)
   • --input / -i: Specify input file (alternative to stdin)

2. svgo configuration:

   • --config: Load custom svgo config file
   • --preset: Choose optimization presets (default, aggressive, safe)
   • --pretty: Pretty-print output
   • --multipass: Enable multipass optimization

3. Plugin control:

   • --enable-plugin: Enable specific plugins
   • --disable-plugin: Disable specific plugins
   • --list-plugins: Show available plugins

3.2 Improve Error Handling

1. Better error messages

   • Validate input is valid SVG
   • Show line numbers for parsing errors
   • Provide helpful suggestions for common issues

2. Exit codes

   • Use standard Unix exit codes
   • Different codes for different error types
   • Document exit codes in help

4. Code Architecture Improvements

4.1 Refactor Entry Points

Current multiple entry points (svgop-qjs.js, svgop-pkg.js, etc.) have duplicated code.

1. Create shared core module

   • Extract common functionality
   • Use adapter pattern for platform differences
   • Reduce code duplication

2. Improve modularity

   • Separate concerns (I/O, optimization, error handling)
   • Create testable units
   • Use dependency injection

4.2 Add TypeScript Support

1. Benefits:

   • Better IDE support
   • Catch errors at compile time
   • Self-documenting code

2. Implementation:

   • Start with type definitions
   • Gradually convert modules
   • Ensure builds still work with QuickJS

5. Testing and Quality Assurance

5.1 Comprehensive Test Suite

1. Unit tests

   • Test each module independently
   • Mock dependencies
   • Achieve >80% code coverage

2. Integration tests

   • Test full optimization pipeline
   • Compare with reference outputs
   • Test error conditions

3. Performance tests

   • Benchmark optimization speed
   • Track binary size over time
   • Memory usage profiling

5.2 Continuous Integration

1. GitHub Actions workflows

   • Run tests on every PR
   • Build binaries for all platforms
   • Automated releases

2. Quality gates

   • Linting (ESLint)
   • Code formatting (Prettier)
   • Security scanning (npm audit)

6. Documentation Improvements

6.1 User Documentation

1. Comprehensive README

   • Clear installation instructions for all platforms
   • More usage examples
   • Troubleshooting section

2. Man page

   • Create proper Unix man page
   • Include in binary distributions
   • Generate from source

6.2 Developer Documentation

1. Architecture documentation

   • System design diagrams
   • Build process explanation
   • Contributing guidelines

2. API documentation

   • JSDoc comments
   • Generated API docs
   • Examples for extending

7. Distribution and Deployment

7.1 Package Manager Integration

1. Homebrew (macOS)

   • Create formula
   • Submit to homebrew-core
   • Automate updates

2. Scoop (Windows)

   • Create manifest
   • Submit to scoop-extras
   • Automate updates

3. Linux packages

   • Create .deb packages
   • Create .rpm packages
   • Submit to AUR (Arch)

7.2 Improved Release Process

1. Semantic versioning

   • Follow semver strictly
   • Automated changelog generation
   • Git tags for all releases

2. Release artifacts

   • Checksums for all binaries
   • GPG signatures
   • Release notes

8. Performance Optimizations

8.1 Binary Size Reduction

1. Code optimization

   • Remove unused code paths
   • Optimize webpack configuration
   • Use newer compression algorithms

2. Build optimization

   • Experiment with different QuickJS flags
   • Profile binary contents
   • Strip unnecessary symbols

8.2 Runtime Performance

1. Optimization strategies
   • Stream processing for large files
   • Parallel processing where possible
   • Memory usage optimization

Implementation Timeline

Phase 1: Foundation (Weeks 1-2)

• Fix Docker builds
• Update critical dependencies
• Set up CI/CD pipeline

Phase 2: Core Updates (Weeks 3-4)

• Update svgo to latest version
• Refactor build system
• Add basic CLI options

Phase 3: Platform Expansion (Weeks 5-6)

• Add Linux QuickJS builds
• Add Windows QuickJS builds
• Automate all builds

Phase 4: Features and Polish (Weeks 7-8)

• Implement advanced CLI options
• Add comprehensive testing
• Update documentation

Phase 5: Distribution (Weeks 9-10)

• Package manager integration
• Release automation
• Community outreach

Success Metrics

1. Technical metrics:

   • Binary size ≤ 3MB for QuickJS builds
   • Build success rate = 100% on all platforms
   • Test coverage ≥ 80%

2. User metrics:

   • Installation success rate ≥ 95%
   • Issue resolution time < 1 week
   • Active contributors ≥ 5

3. Performance metrics:

   • Optimization speed within 10% of native svgo
   • Memory usage < 100MB for typical files
   • Startup time < 100ms

Risk Mitigation

1. svgo update complexity:

   • Create compatibility layer
   • Maintain legacy branch
   • Gradual migration path

2. Platform-specific issues:

   • Extensive testing matrix
   • Beta testing program
   • Rollback procedures

3. Backwards compatibility:

   • Version output format
   • Support legacy workflows
   • Clear migration guides