feat: Improve dependency traversal for interface inheritance (#14)

This commit introduces several improvements to the dependency traversal
logic, specifically handling interface inheritance scenarios:

1. Correctly extracts dependencies from interfaces that inherit from other
   interfaces, ensuring the correct order of dependencies.
2. Handles multiple interface inheritance, where an interface extends
   multiple other interfaces.
3. Supports nested interface inheritance, where an interface extends an
   interface that extends another interface.

These changes ensure that the dependency traversal algorithm can
accurately identify and order the dependencies for complex interface
inheritance structures, which is crucial for generating correct code.

Author: DaxServer

ARCHITECTURE.md

@@ -70,9 +70,35 @@ The dependency system consists of three main components:
 
 1. **Local Type Collection**: Adds all types from the main source file
 2. **Import Processing**: Recursively processes import declarations
-3. **Dependency Extraction**: Analyzes type references to build dependency graph
+3. **Dependency Extraction**: Analyzes type references to build dependency graph for all supported TypeScript constructs:
+   - **Type Aliases**: Extracts dependencies from type alias declarations
+   - **Interfaces**: Analyzes interface property types and heritage clauses
+   - **Enums**: Processes enum member value dependencies
+   - **Functions**: Extracts dependencies from parameter types, return types, and type parameters
 4. **Topological Sorting**: Returns nodes in proper dependency order
 
+#### Graph Visualization
+
+The system includes interactive graph visualization capabilities through the `GraphVisualizer` utility:
+
+- **Sigma.js Integration**: Uses ES6 modules with unpkg CDN for interactive HTML-based graph visualization
+- **Custom Node Shapes**: Implements WebGL-based custom node programs for different TypeScript constructs:
+  - **Diamond**: Interface types (rotated square program)
+  - **Square**: Type alias declarations
+  - **Triangle**: Enum declarations
+  - **Star**: Function declarations
+  - **Circle**: Default/other types
+- **ForceAtlas2 Layout**: Single optimized layout algorithm for automatic node positioning with gravity and scaling controls
+- **Enhanced Node Differentiation**:
+  - **Size Variation**: Different node sizes based on type and importance (main code vs imported)
+  - **Color Coding**: Type-specific colors with intensity variation based on import nesting level
+  - **Shape Mapping**: Direct visual shape differentiation using custom WebGL node programs
+  - **Visual Legend**: CSS-styled legend showing actual shape representations
+- **Import Nesting Visualization**: Color intensity reflects import depth, with main code having brightest colors
+- **Interactive Features**: Click events for node details, zoom/pan capabilities, and hover tooltips
+- **Export Options**: Generates standalone HTML files with embedded visualization and complete styling
+- **WebGL Programs**: Custom node renderers extending `@sigma/node-square` and `@sigma/node-border` packages
+
 ### Parser System
 
 The parser system is built around a base class architecture in <mcfile name="parsers" path="src/parsers"></mcfile>:

bun.lock

@@ -6,6 +6,7 @@
       "dependencies": {
         "graphology": "^0.26.0",
         "graphology-dag": "^0.4.1",
+        "graphology-layout-forceatlas2": "^0.10.1",
         "graphology-traversal": "^0.3.1",
       },
       "devDependencies": {
@@ -208,6 +209,8 @@
 
     "graphology-indices": ["graphology-indices@0.17.0", "", { "dependencies": { "graphology-utils": "^2.4.2", "mnemonist": "^0.39.0" }, "peerDependencies": { "graphology-types": ">=0.20.0" } }, "sha512-A7RXuKQvdqSWOpn7ZVQo4S33O0vCfPBnUSf7FwE0zNCasqwZVUaCXePuWo5HBpWw68KJcwObZDHpFk6HKH6MYQ=="],
 
+    "graphology-layout-forceatlas2": ["graphology-layout-forceatlas2@0.10.1", "", { "dependencies": { "graphology-utils": "^2.1.0" }, "peerDependencies": { "graphology-types": ">=0.19.0" } }, "sha512-ogzBeF1FvWzjkikrIFwxhlZXvD2+wlY54lqhsrWprcdPjopM2J9HoMweUmIgwaTvY4bUYVimpSsOdvDv1gPRFQ=="],
+
     "graphology-traversal": ["graphology-traversal@0.3.1", "", { "dependencies": { "graphology-indices": "^0.17.0", "graphology-utils": "^2.0.0" }, "peerDependencies": { "graphology-types": ">=0.20.0" } }, "sha512-lGLrLKEDKtNgAKgHVhVftKf3cb/nuWwuVPQZHXRnN90JWn0RSjco/s+NB2ARSlMapEMlbnPgv6j++427yTnU3Q=="],
 
     "graphology-types": ["graphology-types@0.24.8", "", {}, "sha512-hDRKYXa8TsoZHjgEaysSRyPdT6uB78Ci8WnjgbStlQysz7xR52PInxNsmnB7IBOM1BhikxkNyCVEFgmPKnpx3Q=="],

package.json

@@ -1,8 +1,17 @@
 {
   "name": "@daxserver/validation-schema-codegen",
   "version": "0.1.0",
+  "description": "Codegen for validation schemas",
+  "private": true,
   "main": "src/index.ts",
   "module": "src/index.ts",
+  "type": "module",
+  "dependencies": {
+    "graphology": "^0.26.0",
+    "graphology-dag": "^0.4.1",
+    "graphology-layout-forceatlas2": "^0.10.1",
+    "graphology-traversal": "^0.3.1"
+  },
   "devDependencies": {
     "@eslint/js": "^9.34.0",
     "@prettier/sync": "^0.6.1",
@@ -26,17 +35,9 @@
   "peerDependencies": {
     "typescript": "~5.9.2"
   },
-  "description": "Codegen for validation schemas",
-  "private": true,
   "scripts": {
     "format": "prettier --cache --write .",
     "typecheck": "tsc --noEmit",
     "lint": "eslint"
-  },
-  "type": "module",
-  "dependencies": {
-    "graphology": "^0.26.0",
-    "graphology-dag": "^0.4.1",
-    "graphology-traversal": "^0.3.1"
   }
 }

src/index.ts

@@ -5,6 +5,7 @@ import {
 import { TypeBoxPrinter } from '@daxserver/validation-schema-codegen/printer/typebox-printer'
 import { DependencyTraversal } from '@daxserver/validation-schema-codegen/traverse/dependency-traversal'
 import type { TraversedNode } from '@daxserver/validation-schema-codegen/traverse/types'
+import type { VisualizationOptions } from '@daxserver/validation-schema-codegen/utils/graph-visualizer'
 import { Node, Project, SourceFile, ts } from 'ts-morph'
 
 const createOutputFile = (hasGenericInterfaces: boolean) => {
@@ -50,13 +51,25 @@ const printSortedNodes = (sortedTraversedNodes: TraversedNode[], newSourceFile:
   return newSourceFile.getFullText()
 }
 
-export const generateCode = ({ sourceCode, filePath, ...options }: InputOptions): string => {
+export interface CodeGenerationOptions extends InputOptions {
+  visualizationOptions?: VisualizationOptions
+}
+
+export const generateVisualization = async (options: CodeGenerationOptions): Promise<string> => {
   // Create source file from input
-  const sourceFile = createSourceFileFromInput({
-    sourceCode,
-    filePath,
-    ...options,
-  })
+  const sourceFile = createSourceFileFromInput(options)
+
+  // Create dependency traversal and start traversal
+  const dependencyTraversal = new DependencyTraversal()
+  dependencyTraversal.startTraversal(sourceFile)
+
+  // Generate visualization
+  return await dependencyTraversal.visualizeGraph(options.visualizationOptions)
+}
+
+export const generateCode = (options: InputOptions): string => {
+  // Create source file from input
+  const sourceFile = createSourceFileFromInput(options)
 
   // Create dependency traversal and start traversal
   const dependencyTraversal = new DependencyTraversal()

src/traverse/dependency-traversal.ts

@@ -2,14 +2,20 @@ import { FileGraph } from '@daxserver/validation-schema-codegen/traverse/file-gr
 import { NodeGraph } from '@daxserver/validation-schema-codegen/traverse/node-graph'
 import type { TraversedNode } from '@daxserver/validation-schema-codegen/traverse/types'
 import { generateQualifiedNodeName } from '@daxserver/validation-schema-codegen/utils/generate-qualified-name'
-import { topologicalSort } from 'graphology-dag'
 import {
+  GraphVisualizer,
+  type VisualizationOptions,
+} from '@daxserver/validation-schema-codegen/utils/graph-visualizer'
+import { hasCycle, topologicalSort } from 'graphology-dag'
+import {
+  EnumDeclaration,
+  FunctionDeclaration,
   ImportDeclaration,
   InterfaceDeclaration,
   Node,
   SourceFile,
+  SyntaxKind,
   TypeAliasDeclaration,
-  TypeReferenceNode,
 } from 'ts-morph'
 
 /**
@@ -113,32 +119,29 @@ export class DependencyTraversal {
    * Extract dependencies for all nodes in the graph
    */
   extractDependencies(): void {
-    // Extract dependencies for all nodes in the graph
     for (const nodeId of this.nodeGraph.nodes()) {
       const nodeData = this.nodeGraph.getNode(nodeId)
 
+      let nodeToAnalyze: Node | undefined
+
       if (nodeData.type === 'typeAlias') {
         const typeAlias = nodeData.node as TypeAliasDeclaration
-        const typeNode = typeAlias.getTypeNode()
-        if (!typeNode) continue
+        nodeToAnalyze = typeAlias.getTypeNode()
+      } else if (nodeData.type === 'interface') {
+        nodeToAnalyze = nodeData.node as InterfaceDeclaration
+      } else if (nodeData.type === 'enum') {
+        nodeToAnalyze = nodeData.node as EnumDeclaration
+      } else if (nodeData.type === 'function') {
+        nodeToAnalyze = nodeData.node as FunctionDeclaration
+      }
 
-        const typeReferences = this.extractTypeReferences(typeNode)
+      if (!nodeToAnalyze) continue
 
-        // Add edges for dependencies
-        for (const referencedType of typeReferences) {
-          if (this.nodeGraph.hasNode(referencedType)) {
-            this.nodeGraph.addDependency(referencedType, nodeId)
-          }
-        }
-      } else if (nodeData.type === 'interface') {
-        const interfaceDecl = nodeData.node as InterfaceDeclaration
-        const typeReferences = this.extractTypeReferences(interfaceDecl)
+      const typeReferences = this.extractTypeReferences(nodeToAnalyze)
 
-        // Add edges for dependencies
-        for (const referencedType of typeReferences) {
-          if (this.nodeGraph.hasNode(referencedType)) {
-            this.nodeGraph.addDependency(referencedType, nodeId)
-          }
+      for (const referencedType of typeReferences) {
+        if (this.nodeGraph.hasNode(referencedType)) {
+          this.nodeGraph.addDependency(referencedType, nodeId)
         }
       }
     }
@@ -229,21 +232,29 @@ export class DependencyTraversal {
   }
 
   /**
-   * Get nodes in dependency order (dependencies first)
-   * Retrieved from the graph, not from SourceFile
+   * Get nodes in dependency order from graph
+   * Handles circular dependencies gracefully by falling back to simple node order
    */
   getNodesToPrint(): TraversedNode[] {
-    try {
-      // Use topological sort to ensure dependencies are printed first
-      const sortedNodeIds = topologicalSort(this.nodeGraph)
-      return sortedNodeIds.map((nodeId: string) => this.nodeGraph.getNodeAttributes(nodeId))
-    } catch {
-      // Handle circular dependencies by returning nodes in insertion order
-      // This ensures dependencies are still processed before dependents when possible
-      return Array.from(this.nodeGraph.nodes()).map((nodeId: string) =>
-        this.nodeGraph.getNodeAttributes(nodeId),
-      )
-    }
+    const nodes = hasCycle(this.nodeGraph)
+      ? Array.from(this.nodeGraph.nodes())
+      : topologicalSort(this.nodeGraph)
+
+    return nodes.map((nodeId: string) => this.nodeGraph.getNode(nodeId))
+  }
+
+  /**
+   * Generate HTML visualization of the dependency graph
+   */
+  async visualizeGraph(options: VisualizationOptions = {}): Promise<string> {
+    return GraphVisualizer.generateVisualization(this.nodeGraph, options)
+  }
+
+  /**
+   * Get the node graph for debugging purposes
+   */
+  getNodeGraph(): NodeGraph {
+    return this.nodeGraph
   }
 
   private extractTypeReferences(node: Node): string[] {
@@ -255,8 +266,7 @@ export class DependencyTraversal {
       visited.add(node)
 
       if (Node.isTypeReference(node)) {
-        const typeRefNode = node as TypeReferenceNode
-        const typeName = typeRefNode.getTypeName().getText()
+        const typeName = node.getTypeName().getText()
 
         for (const qualifiedName of this.nodeGraph.nodes()) {
           const nodeData = this.nodeGraph.getNode(qualifiedName)
@@ -265,8 +275,44 @@ export class DependencyTraversal {
             break
           }
         }
+      }
 
-        return
+      // Handle typeof expressions (TypeQuery nodes)
+      if (Node.isTypeQuery(node)) {
+        const exprName = node.getExprName()
+
+        if (Node.isIdentifier(exprName) || Node.isQualifiedName(exprName)) {
+          const typeName = exprName.getText()
+
+          for (const qualifiedName of this.nodeGraph.nodes()) {
+            const nodeData = this.nodeGraph.getNode(qualifiedName)
+            if (nodeData.originalName === typeName) {
+              references.push(qualifiedName)
+              break
+            }
+          }
+        }
+      }
+
+      // Handle interface inheritance (extends clauses)
+      if (Node.isInterfaceDeclaration(node)) {
+        const heritageClauses = node.getHeritageClauses()
+
+        for (const heritageClause of heritageClauses) {
+          if (heritageClause.getToken() !== SyntaxKind.ExtendsKeyword) continue
+
+          for (const typeNode of heritageClause.getTypeNodes()) {
+            const typeName = typeNode.getText()
+
+            for (const qualifiedName of this.nodeGraph.nodes()) {
+              const nodeData = this.nodeGraph.getNode(qualifiedName)
+              if (nodeData.originalName === typeName) {
+                references.push(qualifiedName)
+                break
+              }
+            }
+          }
+        }
       }
 
       node.forEachChild(traverse)

src/traverse/node-graph.ts

@@ -22,36 +22,19 @@ export class NodeGraph extends DirectedGraph<TraversedNode> {
     return this.getNodeAttributes(qualifiedName) as TraversedNode
   }
 
-  /**
-   * Remove unused imported nodes that have no outgoing edges
-   * Never removes root imports (types directly imported from the main file)
-   */
-  removeUnusedImportedNodes(): void {
-    const nodesToRemove: string[] = []
-
-    for (const nodeId of this.nodes()) {
-      const nodeData = this.getNodeAttributes(nodeId)
-      if (nodeData?.isImported && !nodeData?.isMainCode) {
-        // Check if this imported type has any outgoing edges (other nodes depend on it)
-        const outgoingEdges = this.outboundNeighbors(nodeId)
-        if (outgoingEdges.length === 0) {
-          nodesToRemove.push(nodeId)
-        }
-      }
-    }
-
-    // Remove unused imported types
-    for (const nodeId of nodesToRemove) {
-      this.dropNode(nodeId)
-    }
-  }
-
   /**
    * Add dependency edge between two nodes
    */
   addDependency(fromNode: string, toNode: string): void {
-    if (this.hasNode(fromNode) && this.hasNode(toNode)) {
-      this.addDirectedEdge(fromNode, toNode)
+    if (
+      !this.hasNode(fromNode) ||
+      !this.hasNode(toNode) ||
+      fromNode === toNode ||
+      this.hasDirectedEdge(fromNode, toNode)
+    ) {
+      return
     }
+
+    this.addDirectedEdge(fromNode, toNode)
   }
 }