@madnessengineering/uml-generator 0.1.0

package/EXAMPLES.md

@@ -0,0 +1,249 @@
+# 🔍 SwarmDesk UML Generator - Examples
+
+## 📚 Real-World Examples
+
+### 1. Analyze Inventorium (Current Project)
+```bash
+node uml-generator.js .. --output inventorium-uml.json
+```
+
+### 2. Analyze Just the Components Directory
+```bash
+node uml-generator.js ../src/components --output components-only.json
+```
+
+### 3. Analyze a Public GitHub Repo (React)
+```bash
+# Note: This clones the repo temporarily, analyzes it, then cleans up
+node uml-generator.js https://github.com/facebook/react
+```
+
+### 4. Analyze Three.js Library
+```bash
+node uml-generator.js https://github.com/mrdoob/three.js --output three-uml.json
+```
+
+### 5. Analyze Your Own GitHub Project
+```bash
+node uml-generator.js https://github.com/yourusername/your-project
+```
+
+### 6. Custom Include/Exclude Patterns
+```bash
+# Only analyze source code, skip tests and config
+node uml-generator.js . \
+  --include "src,lib" \
+  --exclude "test,__tests__,config,scripts,node_modules"
+```
+
+### 7. Analyze Multiple Related Projects
+```bash
+# Generate UML for each project in your workspace
+node uml-generator.js ~/projects/frontend --output frontend-uml.json
+node uml-generator.js ~/projects/backend --output backend-uml.json
+node uml-generator.js ~/projects/shared --output shared-uml.json
+```
+
+## 🎮 Loading in SwarmDesk
+
+### Method 1: Copy to Data Directory
+```bash
+# Generate UML
+node uml-generator.js ~/my-project --output my-project-uml.json
+
+# Copy to SwarmDesk data folder
+cp my-project-uml.json ../public/data/
+
+# Access in browser
+open http://localhost:3000?uml=my-project-uml.json
+```
+
+### Method 2: Use URL Parameter
+1. Start SwarmDesk server: `npm start` (from Inventorium root)
+2. Place your UML file in `public/data/`
+3. Navigate to: `http://localhost:3000?uml=your-file.json`
+
+### Method 3: Press 'I' Key to Cycle Data Sources
+1. Load SwarmDesk
+2. Press `I` key to cycle through available UML data sources
+3. Your newly generated files will appear in the cycle
+
+## 🔧 Advanced Usage
+
+### GitHub Private Repos (Future Enhancement)
+```bash
+# Not yet implemented, but planned:
+# node uml-generator.js https://github.com/private/repo --token YOUR_TOKEN
+```
+
+### With Custom NPM Script
+Add to your project's `package.json`:
+```json
+{
+  "scripts": {
+    "visualize": "node ../SwarmDesk/uml-generator.js . --output ../public/data/my-uml.json"
+  }
+}
+```
+
+Then run:
+```bash
+npm run visualize
+```
+
+### Automated CI/CD Integration
+```yaml
+# .github/workflows/visualize.yml
+name: Generate 3D Visualization
+on: [push]
+jobs:
+  visualize:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Generate UML
+        run: |
+          npm install comment-parser
+          node tools/uml-generator.js . --output visualization.json
+      - name: Upload artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: code-visualization
+          path: visualization.json
+```
+
+## 📊 Interpreting the Output
+
+### Understanding the Metrics
+
+**Lines of Code:**
+- Small components: < 100 lines → Short buildings
+- Medium components: 100-300 lines → Medium buildings
+- Large components: > 300 lines → Tall buildings
+
+**Complexity:**
+- Low: < 10 (if/for/while) → Green/Cool colors
+- Medium: 10-20 → Yellow/Warm colors
+- High: > 20 → Red/Hot colors
+
+**Git Metrics:**
+- `commitCount`: How many times this file changed
+- `daysAgo`: Recency of last change
+- Frequent changes + recent = Active development area
+
+### Building Colors in SwarmDesk
+
+Press `F6` to cycle through visualization metrics:
+- **Test Coverage**: Green (high) to Red (low)
+- **Code Complexity**: Cool (simple) to Hot (complex)
+- **Method Count**: Indicates file responsibility size
+
+### Dependency Lines
+
+Press `F8` to toggle dependency visualization:
+- **Yellow lines**: Standard dependencies/imports
+- **Orange lines**: Class inheritance (extends)
+- **Cyan lines**: Interface implementations
+- **Green lines**: Module imports
+
+Press `F7` to toggle animated arrows showing data flow direction!
+
+## 🎯 Use Case Scenarios
+
+### Scenario 1: Exploring a New Codebase
+```bash
+# First time seeing a large React app
+node uml-generator.js https://github.com/company/new-project
+
+# Explore in 3D:
+# 1. See package structure (tall vs short buildings)
+# 2. Find main entry points (highly connected nodes)
+# 3. Identify isolated modules (few dependencies)
+```
+
+### Scenario 2: Architecture Review
+```bash
+# Generate UML before refactoring
+node uml-generator.js . --output before-refactor.json
+
+# After refactoring
+node uml-generator.js . --output after-refactor.json
+
+# Compare visually in SwarmDesk
+```
+
+### Scenario 3: Onboarding New Developers
+```bash
+# Generate visualization
+node uml-generator.js . --output team-codebase.json
+
+# Share the 3D view:
+# - New devs can literally "walk through" the code
+# - See how components connect
+# - Identify which areas are most complex
+```
+
+## 🐛 Troubleshooting
+
+### Error: "Path does not exist"
+```bash
+# Make sure path is correct
+ls /path/to/project  # Verify it exists
+
+# Use absolute paths if relative paths aren't working
+node uml-generator.js /absolute/path/to/project
+```
+
+### Error: "git command not found"
+Git metrics will be skipped if Git isn't installed. Generator will still work but won't include commit history.
+
+### Warning: "Could not read package.json"
+Non-critical. The generator will use directory name as project name.
+
+### GitHub Clone Timeout
+```bash
+# For large repos, git clone might timeout
+# Try cloning manually first:
+git clone --depth 1 https://github.com/large/repo temp-repo
+node uml-generator.js temp-repo
+```
+
+## 🚀 Performance Tips
+
+1. **Use `--exclude` aggressively**: Skip test files, generated code, vendor code
+2. **Shallow clones for GitHub**: Automatically uses `--depth 1`
+3. **Include only source dirs**: `--include "src"` is faster than analyzing everything
+4. **Large repos**: Expect 5-10 seconds per 100 files
+
+## 🎨 Customization Ideas
+
+### Create Themed Outputs
+```bash
+# Frontend only
+node uml-generator.js . --include "components,pages" --output frontend.json
+
+# Backend only
+node uml-generator.js . --include "api,services,models" --output backend.json
+
+# Core utilities
+node uml-generator.js . --include "utils,lib,helpers" --output core.json
+```
+
+### Compare Frameworks
+```bash
+# Visualize different framework patterns
+node uml-generator.js https://github.com/react-project --output react-app.json
+node uml-generator.js https://github.com/vue-project --output vue-app.json
+node uml-generator.js https://github.com/angular-project --output angular-app.json
+```
+
+## 📝 Notes
+
+- Output files can be 100KB-1MB for medium projects
+- GitHub clones go to `.swarmdesk-temp/` and are auto-deleted
+- Git metrics require the analyzed directory to be a git repository
+- TypeScript support is basic (treats as JavaScript, no type extraction yet)
+
+---
+
+**🧙‍♂️ Happy Visualizing from the Mad Laboratory!**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mad Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# @madnessengineering/uml-generator
+
+[![npm version](https://badge.fury.io/js/%40madnessengineering%2Fuml-generator.svg)](https://www.npmjs.com/package/@madnessengineering/uml-generator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/node/v/@madnessengineering/uml-generator)](https://nodejs.org)
+
+**Interactive Text User Interface for generating UML city visualizations from any codebase!**
+
+Standalone UML generator for SwarmDesk 3D code visualization - analyze any JavaScript/TypeScript codebase with TypeScript AST parsing, dependency graph analysis, and external library detection.
+
+## 📦 Installation
+
+### Global Installation (Recommended)
+```bash
+npm install -g @madnessengineering/uml-generator
+```
+
+Then run anywhere:
+```bash
+swarmdesk-uml
+# or
+swarmdesk-uml /path/to/project
+# or
+swarmdesk-uml https://github.com/user/repo
+```
+
+### Local Installation
+```bash
+npm install --save-dev @madnessengineering/uml-generator
+```
+
+Add to your package.json scripts:
+```json
+{
+  "scripts": {
+    "visualize": "swarmdesk-uml . --output uml-data.json"
+  }
+}
+```
+
+---
+
+# 🔍⚡ Features
+
+Now featuring a beautiful interactive TUI mode alongside the classic CLI for maximum flexibility.
+
+## ✨ What's New - TUI Mode!
+
+Launch an interactive terminal UI with menus, progress bars, and live previews:
+- 🎨 **Beautiful ASCII art interface** with colored output
+- 📂 **Smart project discovery** - automatically suggests projects from common locations
+- ⚙️ **Interactive configuration** - customize patterns with visual prompts
+- 📊 **Live progress indicators** - watch your analysis happen in real-time
+- 🏙️ **ASCII city preview** - see building heights before loading in 3D
+- 🔄 **Batch analysis** - analyze multiple projects in one session
+
+## 🚀 Quick Start
+
+### Interactive Mode (TUI)
+
+Simply run without arguments to launch the TUI:
+```bash
+cd uml-generator-cli
+npm install
+node uml-generator.js
+# or
+npm start
+```
+
+You'll see:
+- A beautiful SWARMDESK banner
+- Menu to select from suggested projects
+- Options to browse local directories or clone GitHub repos
+- Interactive configuration wizard
+- Real-time analysis progress with spinners
+- Results table with top complexity components
+- ASCII art city preview!
+
+### Classic CLI Mode
+
+For scripts and automation, use with arguments:
+```bash
+# Analyze local directory
+node uml-generator.js /path/to/project
+
+# Analyze GitHub repo
+node uml-generator.js https://github.com/facebook/react
+
+# Custom output with options
+node uml-generator.js . --output my-project.json --include "src,lib"
+
+# Show help
+node uml-generator.js --help
+```
+
+## 📦 Installation
+
+```bash
+cd uml-generator-cli
+npm install
+```
+
+Dependencies include:
+- `inquirer` - Interactive prompts
+- `ora` - Elegant terminal spinners
+- `chalk` - Colorful output
+- `cli-table3` - Beautiful ASCII tables
+- `boxen` - Fancy boxes
+- `gradient-string` - Rainbow gradients
+- `figlet` - ASCII art text
+
+## 🎮 Usage Modes
+
+### 1. TUI Mode (No Arguments)
+**Best for:** Interactive exploration, learning, one-off analyses
+
+```bash
+node uml-generator.js
+```
+
+Features:
+- Project suggestions from common locations
+- Visual menus and prompts
+- Real-time progress feedback
+- Results preview with complexity metrics
+- ASCII art city visualization
+- Multi-project batch processing
+
+### 2. CLI Mode (With Arguments)
+**Best for:** Automation, CI/CD, scripting
+
+```bash
+node uml-generator.js [path|url] [options]
+```
+
+See [UML-GENERATOR-README.md](./UML-GENERATOR-README.md) for full CLI documentation.
+
+## 🎨 TUI Features Showcase
+
+**Smart Project Discovery:**
+- Scans `~/lab`, `~/projects`, `~/dev` for projects
+- Filters for directories with `package.json`
+- Shows suggested projects in menu
+
+**Live Analysis Progress:**
+- 🔄 Scanning project files...
+- 🔍 Analyzing code structure... (23/150 files)
+- 📊 Reading project metadata...
+- ✅ Analysis complete!
+
+**Results Dashboard:**
+```
+┌─────────────────┬────────────────────────────┐
+│ Metric          │ Value                      │
+├─────────────────┼────────────────────────────┤
+│ Project Name    │ my-awesome-project         │
+│ Components      │ 158                        │
+│ Packages        │ 19                         │
+└─────────────────┴────────────────────────────┘
+
+🔥 Most Complex Components:
+┌────────────────────┬────────────┬────────┐
+│ Component          │ Complexity │ Lines  │
+├────────────────────┼────────────┼────────┤
+│ Dashboard          │ 45         │ 523    │
+│ ProjectManager     │ 38         │ 412    │
+└────────────────────┴────────────┴────────┘
+
+🏙️ City Preview (Building Heights):
+  ████ ███ ██ █████ ██ █ ███ ████ ...
+  (Taller = More Lines, Red = Complex, Green = Simple)
+```
+
+## 📝 Notes
+
+### When to Use TUI vs Web UI
+
+**Use TUI when:**
+- Working in terminal environment
+- Analyzing private/local projects
+- Batch processing multiple repos
+- CI/CD automation (CLI mode)
+- No browser available
+
+**Use Web UI (SwarmDesk) when:**
+- Want full 3D visualization
+- Need to explore dependencies interactively
+- Presenting to others
+- Want to navigate the code city
+
+### Compatibility
+
+- **TUI Mode:** Requires TTY (terminal), won't work in pipes
+- **CLI Mode:** Works anywhere, perfect for scripts
+- Auto-detects and falls back gracefully
+
+## 🔮 Advanced Features
+
+- **GitHub cloning:** Automatically clones, analyzes, and cleans up temp repos
+- **Git metrics:** Tracks commit history and file age
+- **Dependency analysis:** Maps import relationships
+- **React-aware:** Special handling for components
+- **Multi-project:** Analyze multiple projects in one session (TUI)
+
+## 🧙‍♂️ From the Mad Laboratory
+
+This TUI edition brings the power of SwarmDesk code visualization to your terminal. Experience the thrill of watching your codebase transform into data, then load it in SwarmDesk for the full 3D city experience!
+
+---
+
+See [EXAMPLES.md](./EXAMPLES.md) for more usage examples.

package/UML-GENERATOR-README.md

@@ -0,0 +1,165 @@
+# 🔍⚡ SwarmDesk UML Generator
+
+Standalone UML generator that analyzes any codebase and creates JSON data for 3D visualization in SwarmDesk!
+
+## ✨ Features
+
+- 📂 **Analyze Local Repositories**: Point it at any project on your machine
+- 🌐 **GitHub Support**: Clone and analyze any public GitHub repository
+- 📊 **Git Metrics**: Track commit history, contributors, and file age
+- 🔗 **Dependency Analysis**: Automatically detect imports and relationships
+- 🎯 **React-Aware**: Special handling for React components
+- 🎨 **3D Ready**: Generates UML JSON that SwarmDesk can visualize
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+cd SwarmDesk
+npm install
+```
+
+### Usage Examples
+
+**Analyze local directory:**
+```bash
+node uml-generator.js /path/to/your/project
+```
+
+**Analyze current directory:**
+```bash
+node uml-generator.js .
+```
+
+**Analyze GitHub repository:**
+```bash
+node uml-generator.js https://github.com/facebook/react
+```
+
+**Custom output file:**
+```bash
+node uml-generator.js . --output my-project-uml.json
+```
+
+**Filter specific directories:**
+```bash
+node uml-generator.js . --include "src,components" --exclude "test,dist,node_modules"
+```
+
+## 📋 Command Line Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `[path]` | Local path or GitHub URL | `./my-project` or `https://github.com/user/repo` |
+| `--output` | Output JSON file path | `--output data/my-uml.json` |
+| `--include` | Comma-separated directories to include | `--include "src,lib,components"` |
+| `--exclude` | Comma-separated patterns to exclude | `--exclude "test,dist,build"` |
+
+## 📊 Output Format
+
+The generator creates a JSON file compatible with SwarmDesk's 3D visualization:
+
+```json
+{
+  "version": "6.0",
+  "generated": "2025-10-30T...",
+  "project": {
+    "name": "my-project",
+    "description": "Project description",
+    "language": "JavaScript"
+  },
+  "packages": [...],
+  "classes": [
+    {
+      "id": "component_abc123",
+      "name": "MyComponent",
+      "type": "class",
+      "subtype": "react_component",
+      "filePath": "src/components/MyComponent.js",
+      "methods": [...],
+      "dependencies": ["Header", "Footer"],
+      "metrics": {
+        "lines": 150,
+        "complexity": 12,
+        "methodCount": 5
+      },
+      "gitMetrics": {
+        "commitCount": 23,
+        "lastCommit": {...}
+      }
+    }
+  ]
+}
+```
+
+## 🎮 Using in SwarmDesk
+
+1. Generate UML for your project:
+   ```bash
+   node uml-generator.js ~/my-project --output my-project-uml.json
+   ```
+
+2. Copy the output file to SwarmDesk data directory:
+   ```bash
+   cp my-project-uml.json ../public/data/
+   ```
+
+3. Load in SwarmDesk by pressing `I` key to cycle data sources, or update the URL:
+   ```
+   http://localhost:3000?uml=my-project-uml.json
+   ```
+
+## 🧪 Testing
+
+Test the generator on itself:
+```bash
+npm test
+```
+
+## 🔧 Supported File Types
+
+- `.js` - JavaScript
+- `.jsx` - React JSX
+- `.ts` - TypeScript
+- `.tsx` - TypeScript React
+- `.mjs` - ES Modules
+
+## 📦 Default Include/Exclude Patterns
+
+**Included by default:**
+- `src/`, `lib/`, `components/`, `pages/`, `utils/`, `hooks/`, `services/`
+
+**Excluded by default:**
+- `node_modules/`, `dist/`, `build/`, `.git/`, `coverage/`, `test/`, `__tests__/`
+
+## 🎯 Use Cases
+
+1. **Explore New Codebases**: Quickly visualize unfamiliar projects in 3D
+2. **Architecture Review**: See dependency relationships and package structure
+3. **Refactoring**: Identify tightly coupled components
+4. **Documentation**: Generate visual documentation of code structure
+5. **Complexity Analysis**: Spot files that might need refactoring
+
+## 🔮 Future Enhancements
+
+- [ ] TypeScript type extraction
+- [ ] JSDoc comment parsing
+- [ ] Test coverage integration
+- [ ] Multiple project comparison
+- [ ] Private GitHub repo support (with tokens)
+- [ ] GitLab/Bitbucket support
+
+## 🧙‍♂️ Mad Laboratory Notes
+
+This tool is part of the Madness Interactive workshop - built for rapid codebase exploration and visualization. We're pushing the boundaries of what's possible with 3D code visualization!
+
+**Pro Tips:**
+- Use with large repos to see amazing 3D cities
+- GitHub URLs automatically clone to `.swarmdesk-temp/` and cleanup after
+- Git metrics work best with repositories that have commit history
+- Combine with SwarmDesk's F7/F8 keys to see dependency arrows
+
+## 📝 License
+
+MIT - Part of the Madness Interactive Laboratory

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@madnessengineering/uml-generator",
+  "version": "0.1.0",
+  "description": "Standalone UML generator for SwarmDesk 3D code visualization - analyze any JavaScript/TypeScript codebase",
+  "main": "uml-generator.js",
+  "bin": {
+    "swarmdesk-uml": "./uml-generator.js"
+  },
+  "scripts": {
+    "start": "node uml-generator.js",
+    "tui": "node tui.js",
+    "generate": "node uml-generator.js",
+    "test": "node uml-generator.js . --output test-output.json"
+  },
+  "keywords": [
+    "uml",
+    "code-visualization",
+    "3d",
+    "swarmdesk",
+    "code-analysis",
+    "ast",
+    "typescript",
+    "javascript",
+    "react",
+    "architecture",
+    "dependency-graph",
+    "static-analysis",
+    "cli",
+    "tui"
+  ],
+  "author": "Mad Laboratory <contact@madnessinteractive.cc>",
+  "license": "MIT",
+  "homepage": "https://github.com/MadTinker/swarmdesk-uml-generator#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MadTinker/swarmdesk-uml-generator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MadTinker/swarmdesk-uml-generator/issues"
+  },
+  "files": [
+    "uml-generator.js",
+    "tui.js",
+    "README.md",
+    "UML-GENERATOR-README.md",
+    "EXAMPLES.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "boxen": "^5.1.2",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.3",
+    "comment-parser": "^1.4.1",
+    "figlet": "^1.6.0",
+    "gradient-string": "^2.0.2",
+    "inquirer": "^8.2.5",
+    "ora": "^5.4.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}