mirror of
https://github.com/imjasonh/apkviz
synced 2026-07-07 01:22:26 +00:00
Add comprehensive documentation for project continuity
README.md: - Complete feature overview and live demo link - Getting started guide with prerequisites and installation - Development and testing instructions - Architecture overview and component descriptions - Visual guide explaining arrow colors and interactions - Usage tips for finding critical packages and analyzing impact - Future enhancement ideas CLAUDE.md: - Critical context for AI assistants working on the project - Technical implementation details and decisions - Common tasks and how to approach them - Testing strategies and debugging tips - Code style guidelines - Known issues and gotchas - Emphasis on Wolfi (not Alpine) and project goals This documentation ensures the project can be effectively maintained and enhanced by future contributors, whether human or AI. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jason Hall
parent
3b643386f0
commit
e933e2bf0f
2 changed files with 276 additions and 0 deletions
134
CLAUDE.md
Normal file
134
CLAUDE.md
Normal file
|
|
@ -0,0 +1,134 @@
|
|||
# CLAUDE.md - Project Context for AI Assistants
|
||||
|
||||
This document provides essential context for AI assistants (particularly Claude) to effectively work on the Wolfi APK Dependency Visualizer project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is a web application that visualizes package dependencies in the Wolfi Linux distribution (NOT Alpine - this is important!). The app provides advanced analytics to help users understand package relationships, identify critical dependencies, and make informed decisions about their system architecture.
|
||||
|
||||
## Critical Context
|
||||
|
||||
### What This Project Does
|
||||
1. **Visualizes Wolfi package dependencies** as an interactive force-directed graph
|
||||
2. **Analyzes package criticality** - which packages are most depended upon
|
||||
3. **Calculates size impact** - total disk space including all dependencies
|
||||
4. **Shows both forward and reverse dependencies** - bidirectional analysis
|
||||
5. **Provides system-wide insights** via the "Most Critical Packages" dashboard
|
||||
|
||||
### Key Technical Decisions
|
||||
- Uses **D3.js force simulation** for graph layout
|
||||
- **TypeScript** for type safety
|
||||
- **Single-page application** with no backend required
|
||||
- **APKINDEX file** (50MB) is pre-downloaded and served statically
|
||||
- **GitHub Pages** deployment via GitHub Actions
|
||||
- **Playwright** for automated browser testing
|
||||
|
||||
## Important Implementation Details
|
||||
|
||||
### Dependency Analysis Algorithm
|
||||
The `DependencyAnalyzer` class provides several key metrics:
|
||||
- **Criticality Score**: Direct dependents + (transitive dependents × 0.5)
|
||||
- **Bus Factor**: Identifies packages that many others depend on
|
||||
- **Total Size Impact**: Recursively calculates package + all dependencies size
|
||||
- **Dependency Depth**: Maximum depth of the dependency tree
|
||||
|
||||
### Visualization Features
|
||||
1. **Three types of dependencies rendered differently**:
|
||||
- Direct dependencies (solid lines)
|
||||
- Transitive dependencies (dashed lines)
|
||||
- Reverse dependencies (red lines, showing what depends on this package)
|
||||
|
||||
2. **Interactive navigation**:
|
||||
- Click any node to re-center the graph on that package
|
||||
- Search box updates to show current package
|
||||
- Package details panel shows analytics
|
||||
|
||||
3. **Performance considerations**:
|
||||
- Graph only shows dependencies to depth 2 by default
|
||||
- Transitive dependencies can be toggled on/off
|
||||
- Force simulation stops after stabilization
|
||||
|
||||
### Testing Infrastructure
|
||||
- All Playwright test outputs go to `playwright-output/` (gitignored)
|
||||
- Test files are prefixed with `test-` or `demo-`
|
||||
- The `quick-debug.js` script provides fast screenshot/console capture
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding New Analytics
|
||||
1. Add analysis methods to `src/dependency-analyzer.ts`
|
||||
2. Update `showPackageStats()` in `src/index.ts` to display results
|
||||
3. Add appropriate styling in `src/styles.css`
|
||||
|
||||
### Modifying the Visualization
|
||||
1. Core D3 logic is in `src/visualization.ts`
|
||||
2. Graph building logic in `buildDependencyGraph()` and `buildTransitiveDependencyGraph()`
|
||||
3. Rendering logic in `renderGraph()`
|
||||
|
||||
### Updating Data
|
||||
```bash
|
||||
npm run fetch-data # Downloads latest APKINDEX from Wolfi
|
||||
```
|
||||
|
||||
### Deployment
|
||||
Pushes to main branch automatically trigger GitHub Actions to:
|
||||
1. Build the project
|
||||
2. Deploy to GitHub Pages at https://imjasonh.github.io/apkviz/
|
||||
|
||||
## Known Issues & Gotchas
|
||||
|
||||
1. **APKINDEX size**: The 50MB file triggers GitHub warnings but works fine
|
||||
2. **Base path**: Production uses `/apkviz/` base path, development uses `/`
|
||||
3. **Tooltip cleanup**: Must properly manage D3 selections to avoid memory leaks
|
||||
4. **Force simulation**: Can be CPU intensive with many nodes
|
||||
|
||||
## Future Enhancement Ideas
|
||||
|
||||
1. **Security analysis**:
|
||||
- Highlight packages with known vulnerabilities
|
||||
- Show security update paths
|
||||
|
||||
2. **Performance optimization**:
|
||||
- Implement virtualization for large graphs
|
||||
- Add WebGL rendering option
|
||||
|
||||
3. **Advanced features**:
|
||||
- Circular dependency detection
|
||||
- Diff between package versions
|
||||
- Export dependency graphs as DOT files
|
||||
|
||||
## Testing Approach
|
||||
|
||||
When testing changes:
|
||||
1. Use `npm start` for development
|
||||
2. Run `node quick-debug.js screenshot` for quick visual checks
|
||||
3. Use `node demo-impressive.js` for full feature demonstration
|
||||
4. Check console for errors with `node quick-debug.js console`
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
1. **TypeScript**: Use proper types, avoid `any` when possible
|
||||
2. **D3.js**: Chain method calls, use arrow functions
|
||||
3. **CSS**: Use CSS classes over inline styles
|
||||
4. **Comments**: Focus on WHY not WHAT
|
||||
5. **Git commits**: Descriptive messages explaining the change
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **This is for Wolfi, NOT Alpine Linux** - Never confuse the two
|
||||
- The visualization should **impress friends and shame enemies**
|
||||
- Focus on **actionable insights** not just pretty graphs
|
||||
- Performance matters - the app should handle thousands of packages
|
||||
- The goal is to make dependency management **understandable and fun**
|
||||
|
||||
## Contact & Context
|
||||
|
||||
This project was created to provide powerful dependency analysis for the Wolfi ecosystem. It should serve as both a practical tool and a showcase of what's possible with modern web technologies and thoughtful data visualization.
|
||||
|
||||
When in doubt, prioritize:
|
||||
1. User experience
|
||||
2. Actionable insights
|
||||
3. Performance
|
||||
4. Visual appeal
|
||||
|
||||
Remember: Great tools make complex systems understandable!
|
||||
142
README.md
Normal file
142
README.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
# Wolfi APK Dependency Visualizer
|
||||
|
||||
An interactive web application for visualizing package dependencies in the [Wolfi](https://wolfi.dev) Linux distribution. Explore the intricate web of dependencies, identify critical packages, and analyze the impact of package choices on your system.
|
||||
|
||||
🌐 **Live Demo**: [https://imjasonh.github.io/apkviz/](https://imjasonh.github.io/apkviz/)
|
||||
|
||||
## Features
|
||||
|
||||
### 🔍 Interactive Dependency Exploration
|
||||
- **Force-directed graph visualization** using D3.js
|
||||
- **Bidirectional dependency analysis**: See both what a package depends on AND what depends on it
|
||||
- **Click any node** to re-center the visualization on that package
|
||||
- **Real-time search** with auto-complete functionality
|
||||
- **Transitive dependencies toggle** to show direct vs. full dependency chains
|
||||
|
||||
### 📊 Advanced Analytics
|
||||
- **Criticality Score**: Discover which packages are most depended upon
|
||||
- **Size Impact Analysis**: Calculate total disk space including all dependencies
|
||||
- **Dependency Depth**: Measure how deep the dependency tree goes
|
||||
- **Bus Factor Warnings**: Identify single points of failure in your system
|
||||
|
||||
### 🏆 System-wide Insights
|
||||
- **"Most Critical Packages" dashboard** showing the heavy hitters
|
||||
- **Percentage of ecosystem** that depends on each package
|
||||
- **Leaf package identification** (packages with no dependents)
|
||||
- **Visual differentiation** between direct, transitive, and reverse dependencies
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
- Node.js 20 or higher
|
||||
- npm
|
||||
|
||||
### Installation
|
||||
```bash
|
||||
git clone https://github.com/imjasonh/apkviz.git
|
||||
cd apkviz
|
||||
npm install
|
||||
```
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Start development server (opens at http://localhost:8081)
|
||||
npm start
|
||||
|
||||
# Run type checking
|
||||
npm run typecheck
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Update APKINDEX data from Wolfi
|
||||
npm run fetch-data
|
||||
```
|
||||
|
||||
### Testing
|
||||
The project includes Playwright-based testing infrastructure:
|
||||
|
||||
```bash
|
||||
# Run browser automation tests
|
||||
npm run debug # Opens browser with DevTools
|
||||
npm run browser-test # Runs headless tests
|
||||
|
||||
# All test outputs are saved to playwright-output/ (gitignored)
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Tech Stack
|
||||
- **TypeScript** for type safety
|
||||
- **D3.js** for force-directed graph visualization
|
||||
- **Webpack** for bundling and development server
|
||||
- **Playwright** for automated testing
|
||||
- **GitHub Actions** for CI/CD
|
||||
- **GitHub Pages** for hosting
|
||||
|
||||
### Key Components
|
||||
- `src/visualization.ts` - Core D3.js visualization logic
|
||||
- `src/dependency-analyzer.ts` - Advanced dependency analysis algorithms
|
||||
- `src/apkindex-parser.ts` - Parses Wolfi's APKINDEX format
|
||||
- `src/index.ts` - Main application entry point
|
||||
|
||||
### Data Source
|
||||
The app analyzes Wolfi's APKINDEX file (50MB) which contains metadata for all packages in the distribution. This file is fetched and stored locally in `public/APKINDEX`.
|
||||
|
||||
## Usage Tips
|
||||
|
||||
### Finding Critical Packages
|
||||
1. Click the "🏆 Show Most Critical" button
|
||||
2. See which packages affect the largest percentage of the ecosystem
|
||||
3. Click any package to explore its dependency graph
|
||||
|
||||
### Analyzing Package Impact
|
||||
1. Search for any package (e.g., "python", "gcc", "nodejs")
|
||||
2. Check the Impact Analysis panel for:
|
||||
- Total size including dependencies
|
||||
- Number of packages that depend on it
|
||||
- Dependency depth score
|
||||
|
||||
### Navigation
|
||||
- **Click nodes** to re-center on that package
|
||||
- **Drag nodes** to rearrange the graph
|
||||
- **Zoom** with mouse wheel or pinch gestures
|
||||
- **Toggle transitive dependencies** to simplify/expand the view
|
||||
|
||||
## Visual Guide
|
||||
|
||||
### Arrow Colors
|
||||
- **Dark blue arrows**: Direct dependencies
|
||||
- **Light blue dashed arrows**: Transitive dependencies
|
||||
- **Red arrows**: Reverse dependencies (packages that depend on this)
|
||||
- **Red dashed arrows**: Transitive reverse dependencies
|
||||
|
||||
### Node Information
|
||||
- **Hover** over nodes to see version and size
|
||||
- **Click** nodes to see full package details and analytics
|
||||
- **Node colors** are automatically assigned for visual distinction
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! The codebase is well-structured for adding new features:
|
||||
|
||||
1. Analytics algorithms go in `src/dependency-analyzer.ts`
|
||||
2. Visualization enhancements in `src/visualization.ts`
|
||||
3. New UI features in `src/index.ts` and `src/index.html`
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Security vulnerability tracking
|
||||
- Package freshness/staleness indicators
|
||||
- Circular dependency detection and visualization
|
||||
- Dependency conflict analysis
|
||||
- Export capabilities (SVG, graph data)
|
||||
- Package comparison tools
|
||||
|
||||
## License
|
||||
|
||||
This project is open source and available under the ISC License.
|
||||
|
||||
---
|
||||
|
||||
Built with ❤️ for the Wolfi community. Special thanks to the Wolfi maintainers for creating such a well-structured package ecosystem.
|
||||
Loading…
Add table
Add a link
Reference in a new issue