Mittens

Visualize your Knit dependency injections like never before

Comment

Project Description

Mittens is a comprehensive visualization and analysis tool designed specifically for TikTok's Knit dependency injection framework. It transforms complex, invisible dependency relationships into clear, interactive visualizations that developers can use to understand, debug, and optimize their applications.

Key Features and Functionality

Analysis Engine

  • Automatic detection of circular dependencies, ambiguous providers, and configuration issues
  • Statistical accuracy validation with 94%+ precision and <5% false positive rate
  • Multi-source analysis using both build/knit.json and Kotlin source code
  • Real-time issue validation with confidence scoring algorithms

Interactive Graph Visualization

  • Force-directed network layout with physics-based node positioning
  • Pan, zoom, and focus capabilities for exploring large dependency graphs (1000+ nodes)
  • Component filtering by package type (services, models, repositories, payment)
  • Path tracing and dependency relationship highlighting
  • Real-time updates via Server-Sent Events (SSE) IDE Integration
  • Native IntelliJ IDEA plugin with Tools menu integration
  • Keyboard shortcuts for quick access (Ctrl+Alt+K for analysis, Ctrl+Alt+G for graphs)
  • Embedded JCEF browser for seamless in-IDE visualization
  • Comprehensive error reporting with suggested fixes and refactoring tips
  • Background processing with detailed progress indicators

Dual-Mode Operation

  • Embedded web view within IntelliJ IDEA for integrated workflow
  • Standalone browser interface for team collaboration and sharing
  • JSON export capabilities for external tool integration
  • Screenshot and permalink generation for documentation

Development Tools Used

IntelliJ Platform Development

  • Kotlin JVM (2.0.21) - Primary language with coroutines for async processing
  • Gradle IntelliJ Plugin (2.7.2) - Plugin development lifecycle management
  • IntelliJ Platform SDK (2024.2) - IDE integration APIs and services
  • JCEF Browser - Embedded Chromium for web view integration

Frontend Visualization

  • Next.js (15.0.1) - React framework with App Router architecture
  • React (19.0.0-rc) - UI library with concurrent features and server components
  • TypeScript (5.5.4) - Type-safe development with strict checking
  • D3.js (7.8.5) - Low-level graph manipulation and custom force layouts
  • VisActor/VChart (1.12.10) - High-performance chart rendering engine

Build and Development Infrastructure

  • Gradle (8.7) - Build automation with Kotlin DSL
  • JDK 17+ - Runtime environment for plugin and build processes
  • Node.js 18+ - JavaScript runtime for UI development
  • ESLint + Prettier - Code quality and formatting tools

APIs Used in the Project

IntelliJ Platform APIs

  • Project Structure API - Access to project files, modules, and source roots
  • Notification API - User feedback via balloon notifications and event log
  • Progress API - Background task execution with cancellation support
  • File System API - Reading project files and generating temporary exports
  • Action System API - Menu integration and keyboard shortcut registration

Gradle Tooling API

  • Build Integration - Programmatic execution of shadowJarWithKnit tasks
  • Task Management - Progress monitoring and error handling for Gradle operations
  • Project Model Access - Reading build configuration and dependency information

Custom REST APIs (Next.js)

  • POST /api/import-data - Receives dependency graph JSON from IntelliJ plugin
  • GET /api/import-data - Returns latest imported analysis data for UI rendering
  • POST /api/refresh - Triggers sample project rebuild and data import
  • GET /api/stream - Server-Sent Events endpoint for real-time graph updates

Kotlin Analysis API

  • Component Detection - Finding @Component, @Provides, and dependency injection points
  • Type Resolution - Analyzing dependency types and injection relationships

Assets Used in the Project

Visual Design Assets

  • SVG Icons - Custom plugin icons and UI element graphics
  • TailwindCSS Design System - Color palettes, typography scales, and animation utilities
  • Radix UI Components - Accessible dropdown menus, popovers, and form controls

Sample Data and Configuration

  • Demo E-commerce Project - Realistic Kotlin application with intentional DI issues
  • Configuration Templates - Pre-configured Knit plugin settings and build scripts
  • Analysis Test Cases - Comprehensive examples of all DI error types for validation

Libraries Used in the Project

JSON Processing and Serialization

  • Jackson JSON (2.15.2) - High-performance JSON parsing with Kotlin module support
  • Jackson Databind - Object mapping for complex analysis result serialization
  • Jackson Module Kotlin - Kotlin-specific features like null safety and data classes

State Management and UI Components

  • Jotai (2.10.1) - Atomic state management for complex graph data
  • Radix UI React Components - Accessible component primitives (dropdowns, popovers, slots)
  • Lucide React (0.436.0) - Consistent SVG icon library
  • clsx + class-variance-authority - Conditional styling and component variants

Styling and Theme Management

  • TailwindCSS (3.4.1) - Utility-first CSS framework with custom design system
  • tailwind-merge (2.5.2) - Intelligent Tailwind class merging
  • tailwindcss-animate (1.0.7) - Animation utilities and keyframes
  • next-themes (0.3.0) - Dark/light theme switching with persistence

Development and Quality Tools

  • @typescript-eslint/ (8.3.0) - TypeScript-specific linting rules
  • prettier-plugin-sort-imports (4.3.0) - Automatic import organization
  • prettier-plugin-tailwindcss (0.6.6) - Tailwind class sorting and formatting

The Relevant Problem Statement

Challenge: TikTok's Knit dependency injection framework delivers exceptional performance through direct bytecode manipulation, but this approach creates a critical visibility problem. Unlike traditional DI frameworks that generate intermediate code, Knit's bytecode-level transformations make dependency relationships completely opaque to developers.

Impact on Development:

  • Architectural Complexity: As applications scale to hundreds of components, developers lose track of dependency relationships, leading to tightly coupled code and circular dependencies
  • Debugging Difficulties: DI issues like ambiguous providers or missing components only surface at build time with cryptic error messages
  • Team Onboarding: New developers struggle to understand complex dependency structures without visual guidance
  • Technical Debt: Hidden architectural problems accumulate over time, affecting maintainability and performance

Market Gap: Existing dependency analysis tools focus on runtime frameworks like Spring or Dagger, leaving Knit developers without specialized tooling for their unique bytecode-based approach.

## Explanation of How to Use the Tool's Features

Getting Started

  1. Plugin Installation # Build and install the plugin cd mittens && ./gradlew buildPlugin # Install ZIP from build/distributions/ in IntelliJ: Settings → Plugins → Install from Disk # Turn off K2 mode for Kotlin in IntelliJ: Settings → Languages & Frameworks → Kotlin → Uncheck Enable K2 mode
  2. UI Server Setup # Start the visualization interface cd view/mittens && npm install && npm run dev # UI runs at http://localhost:3000 if ran locally or hosted on https://mittens-two.vercel.app

Running Analysis

  1. Project Configuration (Required) // Add to your project's build.gradle.kts extensions.getByType().apply { dependencyTreeOutputPath.set("build/knit.json") }
  2. Execute Analysis
    • Use keyboard shortcut: Ctrl+Alt+K (Run Knit Analysis)
    • Or navigate: Tools → Knit Analysis → Run Knit Analysis
    • Plugin analyzes source code and triggers Gradle shadowJarWithKnit task
  3. Review Results
    • Analysis notification appears with summary statistics
    • Click "View Full Report" for detailed issue breakdown
    • Access "Analysis Tips" for fixing detected problems

Interactive Visualization

  1. Open Graph View
    • Use keyboard shortcut: Ctrl+Alt+G (Open Dependency Graph)
    • Or navigate: Tools → Knit Analysis → Open Knit Dependency Graph
    • JCEF browser opens with embedded visualization
  2. Navigation Features
    • Pan: Click and drag to move around large graphs
    • Zoom: Mouse wheel or pinch gestures for scaling
    • Node Selection: Click nodes to view detailed component information
    • Filtering: Use component type buttons (Models, Services, Repositories)
  3. Issue Investigation
    • Purple Nodes: Components with critical errors (circular dependencies)
    • Red Nodes: Components with warnings (ambiguous providers)
    • Path Highlighting: Visual emphasis on dependency relationships
    • Details Panel: Shows component metadata, error descriptions, and suggested fixes

Advanced Features

  1. Export and Sharing
    • Click "Export JSON" to save complete analysis data
  2. Real-time Updates
    • Make code changes in IDE
    • Re-run analysis with Ctrl+Alt+K
    • Graph automatically refreshes with new dependency structure
  3. Sample Project Testing # Test with included demo project cd sample_project && ./gradlew shadowJarWithKnit # Or use UI refresh: curl -X POST {frontend_link}/api/refresh

🔧 Troubleshooting Common Issues

  • "Web view not available": Ensure UI server is running at hosted link or localhost:3000
  • "No Knit tasks found": Verify KnitExtension configuration in build.gradle.kts
  • Graph not updating: Check plugin successfully POSTed to /api/import-data

Built With

Share this project:

Updates