add: comprehensive TDD test infrastructure

- Add Vitest + jsdom testing framework - Create unit tests for engine.js and generator.js - Add integration tests for end-to-end workflows - Include test utilities and setup helpers - Document testing approach in TESTING.md - Document all dependencies in DEPENDS.md - Add Makefile with test targets and dev workflow 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 23:36:22 +01:00
parent eeebdd72d5
commit 2090e372bd
10 changed files with 1320 additions and 0 deletions
--- a/DEPENDS.md
+++ b/DEPENDS.md
@@ -0,0 +1,189 @@
+# Dependencies - Timeline SVG Generator
+
+This document lists all third-party libraries and tools used in the Timeline SVG Generator project.
+
+## Runtime Dependencies
+
+### Production Dependencies
+
+#### PapaParse
+- **Version**: 5.4.1
+- **Source**: https://cdn.jsdelivr.net/npm/papaparse@5.4.1/papaparse.min.js
+- **Purpose**: CSV parsing and processing
+- **License**: MIT
+- **Usage**: Loaded via CDN in index.html:6
+- **Documentation**: https://www.papaparse.com/
+- **Why chosen**: Robust CSV parser with header support, handles edge cases, small footprint
+
+## Development Dependencies
+
+### Testing Framework
+
+#### Vitest
+- **Version**: ^2.1.0
+- **Purpose**: Modern test runner and framework
+- **License**: MIT
+- **Documentation**: https://vitest.dev/
+- **Features**: Fast execution, ESM support, built-in coverage, watch mode
+
+#### @vitest/ui
+- **Version**: ^2.1.0
+- **Purpose**: Browser-based test UI and visualization
+- **License**: MIT
+- **Usage**: `npm run test:ui`
+
+#### @vitest/coverage-v8
+- **Version**: ^2.1.0
+- **Purpose**: Code coverage reporting using V8 engine
+- **License**: MIT
+- **Usage**: `npm run test:coverage`
+
+#### jsdom
+- **Version**: ^25.0.0
+- **Purpose**: DOM environment simulation for Node.js testing
+- **License**: MIT
+- **Documentation**: https://github.com/jsdom/jsdom
+- **Usage**: Enables testing of browser APIs and DOM manipulation
+
+## System Requirements
+
+### Node.js
+- **Minimum Version**: 18.0.0
+- **Recommended**: 20.0.0 or later
+- **Purpose**: Development environment and package management
+
+### NPM
+- **Minimum Version**: 8.0.0
+- **Purpose**: Package manager for development dependencies
+
+## Browser Requirements (Production)
+
+### Supported Browsers
+- **Chrome**: 80+
+- **Firefox**: 75+
+- **Safari**: 13+
+- **Edge**: 80+
+
+### Required Browser Features
+- ES6 Modules support
+- Fetch API
+- File API (for file uploads)
+- SVG support
+- CSS Grid and Flexbox
+
+## External Services
+
+### CDN Dependencies
+
+#### jsDelivr
+- **Purpose**: Content Delivery Network for PapaParse
+- **URL**: https://cdn.jsdelivr.net/
+- **Fallback**: None (project requires internet connection)
+- **Alternative**: Could be replaced with local copy
+
+## Font Dependencies
+
+### Inter Font Family
+- **Source**: System fonts (Inter, Arial, sans-serif fallback)
+- **Usage**: Default UI typography in index.html:11
+- **Purpose**: Modern, readable interface typography
+- **Fallback**: Arial → sans-serif
+
+## Development Tools (Optional)
+
+### Recommended IDE Extensions
+- **Vitest**: VS Code extension for integrated test running
+- **JavaScript ES6**: Enhanced JavaScript support
+- **Live Server**: Local development server
+
+### Git
+- **Purpose**: Version control
+- **Required for**: Contributing to the project
+
+## Security Considerations
+
+### CDN Dependencies
+- **Risk**: External dependency on jsDelivr
+- **Mitigation**: Well-established CDN with high uptime
+- **Alternative**: Local hosting of PapaParse possible
+
+### No Backend Dependencies
+- **Advantage**: Reduced attack surface
+- **Note**: All processing happens client-side
+
+## Dependency Management
+
+### Installation
+```bash
+# Install all development dependencies
+npm install
+
+# Production use
+# No installation needed - open index.html in browser
+```
+
+### Updates
+```bash
+# Check for outdated packages
+npm outdated
+
+# Update to latest compatible versions
+npm update
+
+# Update to latest major versions (breaking changes possible)
+npm install package@latest
+```
+
+### Vulnerability Scanning
+```bash
+# Check for security vulnerabilities
+npm audit
+
+# Fix automatically fixable vulnerabilities
+npm audit fix
+```
+
+## License Compatibility
+
+All dependencies use MIT or MIT-compatible licenses:
+- **PapaParse**: MIT License
+- **Vitest**: MIT License
+- **jsdom**: MIT License
+- **@vitest/ui**: MIT License
+- **@vitest/coverage-v8**: MIT License
+
+## Dependency Decision Matrix
+
+| Library | Alternatives Considered | Why Chosen |
+|---------|------------------------|------------|
+| PapaParse | CSV.js, custom parser | Mature, feature-rich, wide browser support |
+| Vitest | Jest, Mocha | Modern, fast, ESM native, zero config |
+| jsdom | happy-dom, playwright | Most mature DOM simulation, wide compatibility |
+
+## Future Dependency Considerations
+
+### Potential Additions
+- **TypeScript**: For type safety (would require build step)
+- **Playwright**: For E2E testing
+- **ESLint**: For code quality
+- **Prettier**: For code formatting
+
+### Minimization Strategy
+The project intentionally keeps dependencies minimal to:
+- Reduce bundle size
+- Minimize security surface
+- Maintain browser compatibility
+- Enable offline usage
+- Simplify deployment
+
+## Monitoring
+
+### Dependency Health
+- Monitor PapaParse for security updates
+- Watch Vitest releases for test improvements
+- Check browser compatibility quarterly
+
+### Performance Impact
+- PapaParse: ~45KB minified
+- No runtime performance impact from dev dependencies
+- Zero build step maintains fast development cycle