# 1. Clone repository
git clone https://github.com/rofid-c/codebase-analyzer-mcp.git
cd codebase-analyzer-mcp

# 2. Install dependencies
npm install

# 3. Build project (compile TypeScript)
npm run build

# 4. Verify installation
npm run crawl -- --help

# 1. Download ZIP dari GitHub
# https://github.com/rofid-c/codebase-analyzer-mcp/archive/refs/heads/main.zip

# 2. Extract ZIP file
# 3. Open terminal di folder extract

# 4. Install dependencies
npm install

# 5. Build project
npm run build

# Install globally (akan tersedia di npm registry)
npm install -g spider-map-mcp

# Gunakan langsung
spider-map crawl --path /path/to/project

# Cek apakah build berhasil
ls dist/

# Harus ada folder:
# - dist/mcp/server.js
# - dist/core/*.js
# - dist/index.js

# Test crawl (output ringkas)
npm run crawl

# Test crawl dengan log detail
npm run crawl -- --verbose

# Output yang diharapkan (tanpa verbose):
# ✅ Spider Map generated successfully!
# ────────────────────────────────────────
#    ⏱️ Time:         0.07s
#    📄 Files:        35
#    🔗 Links:        32
#    ⚡ Entry Points: 7
#    🔥 Hotspots:     1
#    💤 Orphans:      16
#    🚨 Critical:     0

# Auto setup (detect & configure AI assistant otomatis)
npm run setup

# Output:
# 🕷️ Spider Map MCP - Auto Setup 🕷️
# Mendeteksi Claude Desktop...
# ✅ Berhasil ditambahkan ke Claude Desktop
# 🎉 Setup Selesai! Restart aplikasi AI Assistant Anda.

# Scan direktori saat ini (output ringkas)
npm run crawl

# Scan direktori dengan log proses detail (verbose)
npm run crawl -- --verbose

# Scan project tertentu
npm run crawl -- --path "C:\path\to\your\project"

# Auto-indexing mode (file watcher + 2 detik debounce)
npm run crawl -- --watch

# Watch project tertentu dengan log detail
npm run crawl -- --path "/path/to/project" --watch --verbose

npm run setup

{
  "mcpServers": {
    "spider-map": {
      "command": "node",
      "args": ["/path/to/codebase-analyzer-mcp/dist/mcp/server.js"]
    }
  }
}

# Development mode
npm run dev

# Build & preview
npm run build
npm run preview

spider-map-mcp/
├── src/
│   ├── core/                    # Core functionality
│   │   ├── crawler.ts           # File system crawler
│   │   ├── parser.ts            # Multi-language parser
│   │   ├── graph.ts             # Graph builder & impact simulator
│   │   ├── cache.ts             # Caching system
│   │   ├── compressor.ts        # Token compression
│   │   ├── metrics.ts           # Code metrics & change detection
│   │   ├── temporal.ts          # 4D temporal analysis
│   │   ├── temporal-advanced.ts # Advanced temporal queries
│   │   ├── auto-indexer.ts      # Auto-indexing system
│   │   └── types.ts             # TypeScript types
│   ├── mcp/
│   │   └── server.ts            # MCP server implementation
│   ├── ui/
│   │   ├── index.html           # Web UI entry
│   │   ├── main.ts              # 3D visualization logic
│   │   └── style.css            # UI styling
│   └── index.ts                 # CLI entry point
├── scripts/
│   └── setup.js                 # Auto MCP setup
├── public/                      # Static assets
├── .spidermap/                  # Cache directory
│   └── graph.json               # Cached graph data
├── spider-map.config.ts         # Configuration presets
└── README.md                    # This file

{
  "tool": "configure_auto_indexing",
  "arguments": {
    "projectRoot": "/path/to/project",
    "debounceMs": 3000,
    "enableFileWatcher": true,
    "enablePeriodicSync": false
  }
}

{
  "tool": "get_project_map",
  "arguments": {
    "projectRoot": "/path/to/project",
    "responseMode": "compressed"  // full, summary, compressed, critical-only
  }
}

{
  "tool": "get_file_info",
  "arguments": {
    "projectRoot": "/path/to/project",
    "filePath": "src/models/User.ts"
  }
}

{
  "tool": "simulate_impact",
  "arguments": {
    "projectRoot": "/path/to/project",
    "targetFile": "src/models/User.ts"
  }
}

{
  "changedFile": "src/models/User.ts",
  "directlyAffected": ["src/controllers/UserController.ts", "src/services/AuthService.ts"],
  "indirectlyAffected": ["src/routes/api.ts", "src/index.ts"],
  "totalAffectedCount": 4
}

{
  "tool": "search_files",
  "arguments": {
    "projectRoot": "/path/to/project",
    "filters": {
      "riskLevel": "critical",
      "minImportedByCount": 10,
      "fileCategory": "core"
    }
  }
}

{
  "tool": "get_code_metrics",
  "arguments": {
    "projectRoot": "/path/to/project",
    "filePath": "src/models/User.ts"
  }
}

{
  "tool": "detect_changes",
  "arguments": {
    "projectRoot": "/path/to/project",
    "forceRefresh": false
  }
}

{
  "tool": "get_time_analysis",
  "arguments": {
    "projectRoot": "/path/to/project",
    "timeRange": { "days": 30 },
    "includePositioning": true
  }
}

{
  "tool": "predict_hotspots",
  "arguments": {
    "projectRoot": "/path/to/project",
    "daysAhead": 30,
    "riskThreshold": 50
  }
}

{
  "tool": "query_temporal",
  "arguments": {
    "projectRoot": "/path/to/project",
    "queryType": "trend",
    "trendType": "increasing",
    "minConfidence": 70
  }
}

{
  "tool": "analyze_evolution",
  "arguments": {
    "projectRoot": "/path/to/project",
    "periodDays": 90,
    "includePatterns": true
  }
}

File change detected
         ↓
    [0ms] Queued for update
         ↓
    [1s] More changes... [Reset timer]
         ↓
    [2s] More changes... [Reset timer]
         ↓
    [3s] No more changes
         ↓
    [3000ms] Debounce triggered → Batch reindex
         ↓
    Cache updated ✅

npm run crawl -- --watch

import { initializeAutoIndexer } from './dist/core/auto-indexer.js';

await initializeAutoIndexer({
  projectRoot: '/path/to/project',
  debounceMs: 5000,
  enableFileWatcher: false,
  enablePeriodicSync: true,
  periodicSyncMs: 10 * 60 * 1000  // 10 minutes
});

Dimensi 1: X-axis (Horizontal positioning)
Dimensi 2: Y-axis (Vertical positioning)  
Dimensi 3: Z-axis (Depth/layer positioning)
Dimensi 4: T-axis (Time evolution) ⭐ UNIQUE!

{
  "tool": "get_time_analysis",
  "arguments": {
    "projectRoot": "/path/to/project",
    "timeRange": { "days": 90 },
    "includePositioning": true
  }
}

{
  "temporalMetadata": {
    "totalSnapshots": 45,
    "timeRange": { "start": "2024-05-01", "end": "2024-08-01" },
    "evolutionSummary": {
      "complexityTrend": "increasing",
      "hotspotEvolution": [2, 3, 5, 8, 12],
      "testCoverageEvolution": [45, 52, 58, 61, 65]
    }
  },
  "topEvolvingFiles": [
    {
      "filePath": "src/models/User.ts",
      "complexityTrend": "increasing", 
      "hotspotRisk": 85,
      "stabilityScore": 23,
      "changeFrequency": 0.8,
      "position4D": { "x": 100, "y": 200, "z": 50, "t": 1691234567 }
    }
  ]
}

{
  "tool": "predict_hotspots",
  "arguments": {
    "projectRoot": "/path/to/project", 
    "daysAhead": 30,
    "riskThreshold": 70
  }
}

{
  "predictions": [
    {
      "filePath": "src/services/PaymentService.ts",
      "riskScore": 87,
      "confidence": 92,
      "reasoning": [
        "Complexity increased 40% in last 30 days",
        "Import count doubled recently", 
        "Similar pattern seen in UserService before it became hotspot"
      ],
      "recommendedActions": [
        "Split into smaller modules",
        "Add unit tests (current coverage: 23%)",
        "Refactor before next sprint"
      ]
    }
  ]
}

{
  "tool": "query_temporal", 
  "arguments": {
    "projectRoot": "/path/to/project",
    "queryType": "trend",
    "trendType": "increasing",
    "minConfidence": 80
  }
}

{
  "tool": "analyze_evolution",
  "arguments": {
    "projectRoot": "/path/to/project",
    "periodDays": 180,
    "includePatterns": true
  }
}

// Standard 3D positioning
position3D = {
  x: dependencyComplexity * 10,     // Horizontal spread
  y: importanceLevel * 15,          // Vertical hierarchy  
  z: riskLevel * 20                 // Depth layering
}

// 4D temporal positioning
position4D = {
  ...position3D,
  t: lastModifiedTime,              // Time dimension
  tVelocity: changeFrequency,       // Speed of change
  tAcceleration: complexityGrowth   // Rate of complexity increase
}

// Web UI dapat menampilkan evolusi 3D graph dari waktu ke waktu
// Seperti time-lapse video dependency graph berubah
const timelapseFrames = [
  { timestamp: "2024-01-01", graph: graph_jan },
  { timestamp: "2024-02-01", graph: graph_feb },  
  { timestamp: "2024-03-01", graph: graph_mar },
  // ...
];

// User bisa "play" evolution dan lihat:
// - File mana yang tumbuh jadi hotspot
// - Dependency yang bertambah/berkurang
// - Risk level yang berubah warna

// Node meninggalkan "jejak" pergerakan di 3D space
// Menunjukkan bagaimana posisi file berubah dari waktu ke waktu
fileTrajectory = [
  { time: t1, position: {x: 100, y: 200, z: 50} },
  { time: t2, position: {x: 120, y: 190, z: 75} },  
  { time: t3, position: {x: 150, y: 180, z: 100} }
];

Q: "File mana yang akan bermasalah bulan depan?"
A: predict_hotspots(daysAhead=30) 
   → PaymentService.ts (risk: 87%, confidence: 92%)

Action: Schedule refactoring di sprint planning

Q: "Bagaimana design pattern kita evolusi 6 bulan terakhir?"
A: analyze_evolution(periodDays=180)
   → Coupling meningkat 40%, complexity trend increasing

Action: Implement decoupling strategy

Q: "Sprint mana yang paling risky untuk feature X?"  
A: Check files terkait feature X dengan query_temporal
   → Files akan volatile di minggu ke-3 based on pattern

Action: Schedule feature development di minggu yang lebih stable

Q: "File mana yang sering break CI/CD?"
A: query_temporal(queryType="volatility", threshold=80)
   → List files dengan perubahan tidak konsisten

Action: Add extra monitoring/alerts untuk files tersebut

# Weighted heuristic formula (bukan trained ML model)
features = [
  complexity_growth_rate,          # Bobot 40%
  dependency_change_frequency,     # Bobot 30%
  line_of_code_growth,             # Bobot 20%
  time_between_changes             # Bobot 10%
]

hotspot_risk_score = weighted_sum(features, predefined_weights)
# Skor 0-100 berdasarkan bobot tetap, bukan output model ML

patterns_detected = [
  "cyclic_monthly_change",      # File diubah setiap bulan
  "burst_before_release",       # Perubahan intensif sebelum release
  "weekend_hotfix_pattern",     # Sering di-hotfix weekend
  "dependency_cascade"          # Perubahan memicu perubahan file lain
]

// Enable 4D analysis in spider-map.config.ts
export const temporalConfig = {
  enabled: true,
  snapshotInterval: '1d',        // Daily snapshots
  retentionDays: 365,            // Keep 1 year of data
  predictionHorizon: 30,         // Predict 30 days ahead
  riskThreshold: 70,             // Only show high-risk predictions
  patternMinOccurrences: 3,      // Pattern needs 3+ occurrences
  scoringRecalculation: '7d'     // Recalculate heuristic scores weekly
};

# Development
npm run dev

# Production build
npm run build
npm run preview

// JavaScript/TypeScript
/(?:import|export)\s+(?:[\s\S]*?\s+from\s+)?['"]([^'"]+)['"]/g

// Python
/from\s+([.\w]+)\s+import/g

// PHP/Laravel
/use\s+([^;]+);/g

// Dart/Flutter
/import\s+['"]([^'"]+)['"]/g

// Dan 11+ bahasa lainnya...

BEFORE: "src/models/User.ts" (19 chars) × 100 files = 1900 chars

AFTER:  
  Symbol table: ["src/models/User.ts"] (19 chars, once)
  References: [0, 0, 0, ...] (100 chars)
  Total: 119 chars
  
SAVINGS: 94%!

{
  "v": 1,
  "s": {
    "f": ["file1", "file2"],      // Files
    "c": ["core", "view"],         // Categories
    "r": ["entry", "direct"],      // Roles
    "l": ["critical", "moderate"]  // Risk levels
  },
  "n": [[0,3,21,1,0,0], [1,5,8,1,1,0]],  // Nodes (indices)
  "e": [[1,0], [2,0]]                     // Edges (indices)
}

function simulateImpact(graph: GraphData, fileId: string) {
  const affected = new Set<string>();
  const queue = [fileId];
  const visited = new Set([fileId]);
  
  // Build reverse dependency map
  const importedByMap = buildReverseMap(graph.links);
  
  // BFS traversal
  while (queue.length > 0) {
    const current = queue.shift()!;
    const importers = importedByMap.get(current);
    
    if (importers) {
      for (const importer of importers) {
        if (!visited.has(importer)) {
          visited.add(importer);
          affected.add(importer);
          queue.push(importer);
        }
      }
    }
  }
  
  return affected;
}

// Charge force (repulsion)
charge.strength = -800 - (node.importedByCount * 300);
charge.distanceMax = 1200;

// Link force (attraction)
link.distance = 150 + (srcComplexity + tgtComplexity) * 25;

// Z-axis layering
zForce = (targetZ - currentZ) * 0.02;
node.vz += zForce;

// Radial separation
if (distance < minRadius) {
  force = (minRadius - distance) / distance * 0.1;
  node.v{x,y,z} += {dx,dy,dz} * force;
}

import type { AutoIndexerConfig } from './src/core/auto-indexer.js';

// Development config
export const developmentConfig: AutoIndexerConfig = {
  enabled: true,
  projectRoot: process.cwd(),
  debounceMs: 3000,
  enableFileWatcher: true,
  enablePeriodicSync: false,
  ignorePatterns: [
    'node_modules/**',
    'dist/**',
    'build/**',
    '.git/**',
    '.spidermap/**',
  ],
};

// Production config
export const productionConfig: AutoIndexerConfig = {
  enabled: true,
  projectRoot: process.cwd(),
  debounceMs: 5000,
  enableFileWatcher: false,
  enablePeriodicSync: true,
  periodicSyncMs: 5 * 60 * 1000,  // 5 minutes
  ignorePatterns: [...developmentConfig.ignorePatterns],
};

// Get config based on environment
export function getConfig(): AutoIndexerConfig {
  const env = process.env.NODE_ENV || 'development';
  return env === 'production' ? productionConfig : developmentConfig;
}

# Set project root
PROJECT_ROOT=/path/to/project npm run mcp

# Use production mode
NODE_ENV=production npm run mcp

# Use lightweight mode
NODE_ENV=lightweight npm run mcp

# Error: EACCES permission denied
# Solusi: Gunakan user dengan permission yang benar atau:
sudo npm install  # Linux/Mac
# atau
# Run terminal as Administrator (Windows)

# Error: Cannot find module 'xyz'
# Solusi: Clear cache dan reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# Error: TypeScript compilation failed
# Solusi 1: Check TypeScript version
npm list typescript

# Solusi 2: Reinstall TypeScript
npm install -D typescript@latest

# Solusi 3: Clear dist folder
rm -rf dist
npm run build

# Solusi: Install tsx sebagai dev dependency
npm install -D tsx

# Atau gunakan npx
npx tsx src/index.ts crawl

# Solusi: Disable Windows Defender untuk project folder
# Atau tambahkan folder ke exclusion list
# Settings → Windows Security → Virus & threat protection → Exclusions

# Manual setup required
# Edit file config AI assistant Anda:

# Claude Desktop (Windows)
# File: %APPDATA%\Claude\claude_desktop_config.json

# Claude Desktop (Mac)  
# File: ~/Library/Application Support/Claude/claude_desktop_config.json

# Tambahkan:
{
  "mcpServers": {
    "spider-map": {
      "command": "node",
      "args": ["C:\\FULL\\PATH\\TO\\codebase-analyzer-mcp\\dist\\mcp\\server.js"]
    }
  }
}

AI: "I'll modify User.ts"
*Might break 10 files without knowing*

AI: simulate_impact("User.ts")
→ 4 direct, 8 indirect files affected

AI: "Modifying User.ts will impact 12 files:
     - Direct: UserController, AuthService, ProfileService
     - Indirect: API routes, main entry, 6 more files
     
     I'll update all affected files to maintain consistency."

# Fork repository
# Clone your fork
git clone https://github.com/YOUR_USERNAME/codebase-analyzer-mcp.git

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes
# Test thoroughly
npm run build
npm test

# Commit with clear message
git commit -m "feat: add X language parser"

# Push to your fork
git push origin feature/your-feature-name

# Create Pull Request