dependency-graph-analyzer 1.0.0 → 1.0.1

package/README.MD

@@ -0,0 +1,677 @@
+<div align="center">
+
+>
+
+
+
+# Dependency Graph Analyzer
+
+### Universal dependency graph analysis with cycle detection, Tarjan's algorithm, and GraphViz visualization
+
+[![Node 18+](https://img.shields.io/badge/node-18+-blue.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![npm version](https://badge.fury.io/js/dependency-graph-analyzer.svg)](https://www.npmjs.com/package/dependency-graph-analyzer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GraphQL](https://img.shields.io/badge/GraphQL-API-e10098.svg)](https://graphql.org/)
+[![Live API](https://img.shields.io/badge/API-Live-green.svg)](https://dep-graph-analyzer.shehan.io/graphql)
+
+[Live Demo](https://dep-graph-analyzer.shehan.io/graphql) • [Installation](#-installation) • [Quick Start](#-quick-start) • [API Reference](#-api-reference) • [Examples](#-examples)
+
+</div>
+
+---
+
+## 🎯 Overview
+
+Dependency Graph Analyzer is a **powerful TypeScript library and GraphQL API** that analyzes dependency graphs to detect cycles, find strongly connected components, and visualize relationships.
+
+**It answers the questions:**
+> - ✅ Are there circular dependencies in my system?
+> - ✅ What's the correct build/install order?
+> - ✅ Which packages are most critical?
+> - ✅ How do my components relate to each other?
+
+### Why This Tool?
+
+- **Tarjan's Algorithm** — Find strongly connected components in linear time O(V+E)
+- **Cycle Detection** — Identify circular dependencies with severity levels
+- **Topological Sort** — Get valid dependency ordering
+- **GraphViz Integration** — Beautiful SVG visualizations with highlighted cycles
+- **Universal** — Works for software packages, microservices, courses, teams, or any dependency system
+- **GraphQL API** — Query exactly what you need, nothing more
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| **Cycle Detection** | Finds all circular dependencies with ERROR/WARNING severity |
+| **Tarjan's Algorithm** | Computes strongly connected components efficiently |
+| **Topological Sorting** | Returns valid dependency order (if no cycles exist) |
+| **Critical Package Analysis** | Ranks packages by number of dependents |
+| **GraphViz Visualization** | Generates DOT format and SVG images |
+| **GraphQL API** | Flexible query interface - request only what you need |
+| **TypeScript** | Full type safety and IntelliSense support |
+| **Live API** | Production-ready endpoint at https://dep-graph-analyzer.shehan.io/graphql |
+
+---
+
+## 📦 Installation
+
+### Option 1: Use the Live API (No Installation Required!)
+
+Simply send GraphQL queries to:
+```
+https://dep-graph-analyzer.shehan.io/graphql
+```
+
+**Quick Test:**
+```bash
+curl -X POST https://dep-graph-analyzer.shehan.io/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"C\\\"]}\") { stats { totalNodes hasCycles } } }"}'
+```
+
+### Option 2: Install via NPM ✅
+
+```bash
+npm install dependency-graph-analyzer
+```
+
+**Then use it in your code:**
+
+```typescript
+import { DependencyGraph, GraphAnalyzer, GraphVisualizer } from 'dependency-graph-analyzer';
+
+const graph = new DependencyGraph();
+const g = graph.buildsimple({ 'A': ['B'], 'B': ['C'] });
+
+const analyzer = new GraphAnalyzer(g);
+const result = analyzer.analyze();
+
+console.log(result.stats); // { totalNodes: 3, totalEdges: 2, hasCycles: false }
+```
+
+### Option 3: Install from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/dependency-graph-analyzer.git
+cd dependency-graph-analyzer
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run locally
+npm start
+# Server will start at http://localhost:8092/graphql
+```
+
+---
+
+## 🚀 Quick Start
+
+### Using the Live GraphQL API
+
+**Open in Browser:**
+Visit [https://dep-graph-analyzer.shehan.io/graphql](https://dep-graph-analyzer.shehan.io/graphql)
+
+**Example Query:**
+```graphql
+query {
+  analyze(dependenciesJson: "{\"A\": [\"B\", \"C\"], \"B\": [\"D\"], \"C\": [\"D\"], \"D\": [\"A\"]}") {
+    stats {
+      totalNodes
+      totalEdges
+      hasCycles
+    }
+    cycles {
+      nodes
+      severity
+    }
+    topological {
+      valid
+      order
+    }
+    critical {
+      name
+      dependents
+      rank
+    }
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "analyze": {
+      "stats": {
+        "totalNodes": 4,
+        "totalEdges": 5,
+        "hasCycles": true
+      },
+      "cycles": [
+        {
+          "nodes": ["D", "C", "B", "A"],
+          "severity": "ERROR"
+        }
+      ],
+      "topological": {
+        "valid": false,
+        "order": []
+      },
+      "critical": [
+        {
+          "name": "C",
+          "dependents": 2,
+          "rank": 1
+        }
+      ]
+    }
+  }
+}
+```
+
+### Using as a TypeScript/JavaScript Library
+
+```typescript
+import { DependencyGraph, GraphAnalyzer, GraphVisualizer } from 'dependency-graph-analyzer';
+
+// Define your dependencies
+const dependencies = {
+  'Frontend': ['React', 'API Client'],
+  'React': ['API Client'],
+  'API Client': ['API Server'],
+  'Backend': ['Database', 'API Server'],
+  'API Server': ['Business Logic'],
+  'Business Logic': ['Database'],
+  'Database': []
+};
+
+// Build the graph
+const graph = new DependencyGraph();
+const g = graph.buildsimple(dependencies);
+
+// Analyze it
+const analyzer = new GraphAnalyzer(g);
+const analysis = analyzer.analyze();
+
+// Check for cycles
+if (analysis.stats.hasCycles) {
+  console.log('❌ Circular dependencies found:', analysis.cycles);
+} else {
+  console.log('✅ No cycles! Install order:', analysis.topological.order);
+}
+
+// Find critical packages
+console.log('Most critical packages:', analysis.critical.slice(0, 3));
+
+// Generate visualization
+const visualizer = new GraphVisualizer(g);
+const result = await visualizer.visualize('svg', true, analysis.cycles);
+console.log('SVG:', result.svg);
+```
+
+---
+
+## 🌐 API Reference
+
+### Live GraphQL Endpoint
+
+**Production URL:** `https://dep-graph-analyzer.shehan.io/graphql`
+
+**Local Development:** `http://localhost:8092/graphql` (after running `npm start`)
+
+### GraphQL Schema
+
+```graphql
+type Query {
+  analyze(dependenciesJson: String!): AnalysisResult!
+}
+
+type AnalysisResult {
+  cycles: [Cycle!]!
+  components: [StronglyConnectedComponent!]!
+  topological: TopologicalOrder!
+  critical: [CriticalPackage!]!
+  stats: Stats!
+  visualization: Visualization!
+}
+
+type Cycle {
+  nodes: [String!]!
+  severity: Severity!  # ERROR or WARNING
+}
+
+type StronglyConnectedComponent {
+  nodes: [String!]!
+  size: Int!
+}
+
+type TopologicalOrder {
+  order: [String!]!
+  valid: Boolean!
+}
+
+type CriticalPackage {
+  name: String!
+  dependents: Int!
+  rank: Int!
+}
+
+type Stats {
+  totalNodes: Int!
+  totalEdges: Int!
+  hasCycles: Boolean!
+}
+
+type Visualization {
+  dot: String!   # GraphViz DOT format
+  svg: String    # SVG image (can be rendered in browser)
+}
+```
+
+### Query Examples
+
+**Get only statistics:**
+```graphql
+query {
+  analyze(dependenciesJson: "{\"A\": [\"B\"], \"B\": [\"C\"]}") {
+    stats {
+      totalNodes
+      hasCycles
+    }
+  }
+}
+```
+
+**Get only cycles:**
+```graphql
+query {
+  analyze(dependenciesJson: "{\"express\": [\"body-parser\"], \"body-parser\": [\"express\"]}") {
+    cycles {
+      nodes
+      severity
+    }
+  }
+}
+```
+
+**Get visualization only:**
+```graphql
+query {
+  analyze(dependenciesJson: "{\"A\": [\"B\"], \"B\": [\"C\"]}") {
+    visualization {
+      svg
+    }
+  }
+}
+```
+
+**Get everything:**
+```graphql
+query {
+  analyze(dependenciesJson: "{\"A\": [\"B\"]}") {
+    stats { totalNodes totalEdges hasCycles }
+    cycles { nodes severity }
+    components { nodes size }
+    topological { order valid }
+    critical { name dependents rank }
+    visualization { svg dot }
+  }
+}
+```
+
+---
+
+## 📚 Use Cases & Examples
+
+### Example 1: Software Package Dependencies
+
+**Scenario:** Analyze npm package circular dependencies
+
+```graphql
+query {
+  analyze(dependenciesJson: "{\"express\": [\"body-parser\"], \"body-parser\": [\"express\"], \"morgan\": [\"express\"], \"cors\": []}") {
+    cycles {
+      nodes
+      severity
+    }
+    stats {
+      hasCycles
+    }
+  }
+}
+```
+
+**Expected:** Detects cycle between express ↔ body-parser
+
+### Example 2: Microservices Architecture
+
+**Scenario:** Visualize service dependencies and find tightly coupled components
+
+```graphql
+query {
+  analyze(dependenciesJson: "{\"api-gateway\": [\"auth-service\", \"user-service\"], \"auth-service\": [\"database\", \"cache\"], \"user-service\": [\"database\", \"email-service\"], \"email-service\": [\"queue\"], \"database\": [], \"cache\": [], \"queue\": []}") {
+    stats {
+      totalNodes
+      hasCycles
+    }
+    topological {
+      order
+    }
+    critical {
+      name
+      dependents
+    }
+  }
+}
+```
+
+**Expected:** Database is most critical (3 dependents), no cycles, valid order
+
+### Example 3: Course Prerequisites
+
+**Scenario:** Plan academic path with prerequisite constraints
+
+```graphql
+query {
+  analyze(dependenciesJson: "{\"Advanced AI\": [\"Machine Learning\", \"Linear Algebra\"], \"Machine Learning\": [\"Statistics\", \"Python Programming\"], \"Deep Learning\": [\"Machine Learning\", \"Calculus\"], \"Statistics\": [\"Math 101\"], \"Linear Algebra\": [\"Math 101\"], \"Calculus\": [\"Math 101\"], \"Python Programming\": [], \"Math 101\": []}") {
+    topological {
+      order
+      valid
+    }
+    critical {
+      name
+      dependents
+    }
+  }
+}
+```
+
+**Expected:** Math 101 and Machine Learning are most critical, clear learning path
+
+### Example 4: Build System with Circular Dependency (Error Case)
+
+**Scenario:** Detect circular build dependencies in monorepo
+
+```graphql
+query {
+  analyze(dependenciesJson: "{\"app\": [\"lib-a\", \"lib-b\"], \"lib-a\": [\"lib-c\"], \"lib-b\": [\"lib-c\"], \"lib-c\": [\"lib-a\"]}") {
+    stats {
+      hasCycles
+    }
+    cycles {
+      nodes
+      severity
+    }
+    components {
+      nodes
+      size
+    }
+  }
+}
+```
+
+**Expected:** Cycle detected: lib-a → lib-c → lib-a
+
+### Example 5: Full Stack Architecture Visualization
+
+**Scenario:** Generate architecture diagram with SVG
+
+```graphql
+query {
+  analyze(dependenciesJson: "{\"Frontend\": [\"React\", \"API Client\"], \"React\": [\"API Client\"], \"API Client\": [\"API Server\"], \"Backend\": [\"Database\", \"API Server\"], \"API Server\": [\"Business Logic\"], \"Business Logic\": [\"Database\"], \"Database\": []}") {
+    stats {
+      totalNodes
+      totalEdges
+      hasCycles
+    }
+    topological {
+      order
+    }
+    visualization {
+      svg
+      dot
+    }
+  }
+}
+```
+
+**Expected:** Clean architecture, no cycles, SVG showing layered design
+
+---
+
+## 🧪 Testing
+
+### Test in Browser (GraphQL Playground)
+
+1. Visit: https://dep-graph-analyzer.shehan.io/graphql
+2. Paste any query from examples above
+3. Click "Run"
+4. See results instantly!
+
+### Test with curl
+
+```bash
+# Simple test
+curl -X POST https://dep-graph-analyzer.shehan.io/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"C\\\"]}\") { stats { totalNodes hasCycles } } }"}'
+
+# With cycles
+curl -X POST https://dep-graph-analyzer.shehan.io/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"A\\\"]}\") { cycles { nodes severity } } }"}'
+```
+
+### Test with Postman
+
+1. **Method:** POST
+2. **URL:** `https://dep-graph-analyzer.shehan.io/graphql`
+3. **Headers:** 
+   - `Content-Type: application/json`
+4. **Body (raw JSON):**
+```json
+{
+  "query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"C\\\"]}\") { stats { totalNodes hasCycles } topological { order } } }"
+}
+```
+
+### Test with JavaScript/Node.js
+
+```javascript
+const query = `
+  query {
+    analyze(dependenciesJson: "{\\"A\\": [\\"B\\"], \\"B\\": [\\"C\\"]}") {
+      stats { totalNodes hasCycles }
+      topological { order }
+    }
+  }
+`;
+
+fetch('https://dep-graph-analyzer.shehan.io/graphql', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ query })
+})
+  .then(res => res.json())
+  .then(data => console.log(data));
+```
+
+### Test with Python
+
+```python
+import requests
+
+query = """
+query {
+  analyze(dependenciesJson: "{\\"A\\": [\\"B\\"], \\"B\\": [\\"C\\"]}") {
+    stats { totalNodes hasCycles }
+    topological { order }
+  }
+}
+"""
+
+response = requests.post(
+    'https://dep-graph-analyzer.shehan.io/graphql',
+    json={'query': query},
+    headers={'Content-Type': 'application/json'}
+)
+
+print(response.json())
+```
+
+### Run Local Tests
+
+If you've cloned the repository:
+
+```bash
+# Run test suite
+npm test
+
+# Start local server
+npm run dev
+
+# Test locally
+curl -X POST http://localhost:8092/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"]}\") { stats { totalNodes } } }"}'
+```
+
+---
+
+## 📖 Real-World Test Scenarios
+
+See [examples/REAL_WORLD_TESTS.md](examples/REAL_WORLD_TESTS.md) for 10+ real-world test cases including:
+
+- ✅ Python Django dependencies
+- ✅ Node.js circular dependencies
+- ✅ Microservices architecture
+- ✅ Course prerequisites
+- ✅ Build system cycles
+- ✅ Team skill dependencies
+- ✅ Monorepo analysis
+- ✅ Diamond dependency problem
+
+---
+
+## 🔧 Local Development
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/dependency-graph-analyzer.git
+cd dependency-graph-analyzer
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Start development server
+npm run dev
+```
+
+### Project Structure
+
+```
+dependency-graph-analyzer/
+├── src/
+│   ├── types.ts            # TypeScript interfaces
+│   ├── graph.ts            # Graph building (buildsimple, build)
+│   ├── analyzer.ts         # Tarjan's, cycles, topsort, getcritical
+│   ├── visualizer.ts       # GraphViz integration
+│   ├── schema.ts           # GraphQL schema
+│   ├── resolvers.ts        # GraphQL resolvers
+│   ├── server.ts           # Apollo Server
+│   └── index.ts            # Library exports
+├── examples/
+│   ├── test.ts             # Example usage
+│   ├── viewer.html         # SVG viewer
+│   └── REAL_WORLD_TESTS.md # Test scenarios
+├── dist/                   # Compiled JavaScript (gitignored)
+├── package.json
+├── tsconfig.json
+├── Procfile               # Heroku deployment
+└── README.md
+```
+
+### Available Scripts
+
+```bash
+npm run build    # Compile TypeScript to JavaScript
+npm start        # Run production server (dist/server.js)
+npm run dev      # Run development server with ts-node
+npm test         # Run test suite
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Here's how:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙋 Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/dependency-graph-analyzer/issues)
+- **Live API**: [https://dep-graph-analyzer.shehan.io/graphql](https://dep-graph-analyzer.shehan.io/graphql)
+- **Author**: [@yourusername](https://github.com/yourusername)
+- **Email**: shehan87h@gmail.com
+
+---
+
+## 🌟 Acknowledgments
+
+- Built with [graphlib](https://github.com/dagrejs/graphlib) for graph operations
+- Visualization powered by [GraphViz](https://graphviz.org/) via [@viz-js/viz](https://github.com/viz-js/viz)
+- GraphQL API with [Apollo Server](https://www.apollographql.com/docs/apollo-server/)
+- Deployed on [Heroku](https://www.heroku.com/)
+- Inspired by the need for universal dependency analysis across all domains
+
+---
+
+## 🚀 Key Features Recap
+
+✅ **Tarjan's Algorithm** - O(V+E) complexity for finding SCCs  
+✅ **Cycle Detection** - ERROR/WARNING severity levels  
+✅ **Topological Sort** - Valid build/install ordering  
+✅ **Critical Analysis** - Identify most-depended-on packages  
+✅ **GraphViz Visualization** - SVG/DOT format with cycle highlighting  
+✅ **GraphQL API** - Query exactly what you need  
+✅ **TypeScript** - Full type safety  
+✅ **Live & Production-Ready** - https://dep-graph-analyzer.shehan.io/graphql
+
+---
+
+<div align="center">
+
+**Made by [Shehan Horadagoda](https://github.com/yourusername)**
+
+⭐ Star this repo if you find it useful!
+
+[Try it now →](https://dep-graph-analyzer.shehan.io/graphql)
+
+</div>

package/dist/server.js

@@ -14,6 +14,7 @@ async function startServer() {
         listen: { port },
     });
     console.log(`  Server ready at: ${url}`);
+    ;
 }
 startServer().catch((error) => {
     console.error('Failed to start server:', error);

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;AAAA,2CAA8C;AAC9C,0DAAkE;AAClE,qCAAoC;AACpC,2CAAwC;AAExC,KAAK,UAAU,WAAW;IACxB,MAAM,MAAM,GAAG,IAAI,qBAAY,CAAC;QAC9B,QAAQ,EAAR,iBAAQ;QACR,SAAS,EAAT,qBAAS;KACV,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IAE9C,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,IAAA,kCAAqB,EAAC,MAAM,EAAE;QAClD,MAAM,EAAE,EAAE,IAAI,EAAE;KACjB,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;AAAA,2CAA8C;AAC9C,0DAAkE;AAClE,qCAAoC;AACpC,2CAAwC;AAExC,KAAK,UAAU,WAAW;IACxB,MAAM,MAAM,GAAG,IAAI,qBAAY,CAAC;QAC9B,QAAQ,EAAR,iBAAQ;QACR,SAAS,EAAT,qBAAS;KACV,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IAE9C,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,IAAA,kCAAqB,EAAC,MAAM,EAAE;QAClD,MAAM,EAAE,EAAE,IAAI,EAAE;KACjB,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAC;IAAA,CAAC;AAC5C,CAAC;AAED,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-graph-analyzer",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Universal dependency graph analyzer with cycle detection, Tarjan's algorithm, and GraphViz visualization",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -56,4 +56,4 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }
-}
+}