Comprehensive graph analysis & visualization for nodely environments

[henry-p]

Overview

This PR introduces powerful graph analysis and visualization capabilities for Nodely environments, enabling developers to understand complex data flow structures through both statistical analysis and visual representations.

Key Features

Graph Analysis & Statistics

• Complete dependency extraction from all node types (value, leaf, branch, sequence)
• Recursive pattern detection for >and, >or, and >cond branch structures
• Comprehensive statistics generation including node counts, edge counts, and dependency analysis
• Embedded node support for detailed branch structure analysis

{:total-nodes 23, :total-edges 18
 :node-types {:value 9, :leaf 8, :branch 4, :sequence 2}
 :dependency-counts {:user-age 3, :user-profile 2, :threshold 1, ...}
 :max-dependencies 4}

DOT Graph Visualization

• DOT format generation compatible with Graphviz
• Smart edge labeling showing control flow relationships (condition, truthy, falsey, cond-expr, etc.)
• Embedded node visualization for complex branch structures
• Value preview system with HTML escaping and truncation
• Reflection-based function name extraction using var metadata and source file analysis

Example Visualization

Example of a complex nodely environment with branches, conditions, and embedded nodes visualized as a directed graph.

Usage Example

(comment
  (require '[nodely.analysis.visualize :as viz]
           '[nodely.analysis.visualize-test :refer [comprehensive-test-env]]
           '[clojure.java.io :as io])

  (let [analysis (viz/analyze-nodely-env comprehensive-test-env)
        dot-format (:dot-format analysis)
        filepath "tmp/graph.dot"]
    (println "Stats:" (:statistics analysis))
    (io/make-parents filepath)
    (spit filepath dot-format)))

;; Convert dot to png: $ dot -Tpng tmp/graph.dot -o tmp/graph.png
;; on macOS open like this: $ open "tmp/graph.png"

API Modes:

• (analyze-nodely-env env) - auto-detects source file using reflection
• (analyze-nodely-env env :disabled) - skips function name extraction entirely

Architecture

Analysis Pipeline

1. Node Extraction → Extract all nodes with type information and dependencies
2. Pattern Detection → Identify >and, >or, >cond patterns in branch structures
3. Embedded Node Analysis → Extract inline expressions from complex branches
4. Statistics Generation → Compute comprehensive metrics

Visualization

DOT Generation → Create valid Graphviz format with semantic edge labels and professional styling

Advanced Capabilities

• Pattern Recognition: Automatically detects >cond, >and, >or structures with nested branch support
• Type-Safe Previews: Handles all Clojure data types with smart truncation and HTML escaping
• Edge Semantics: Distinguishes between different control flow relationships

Benefits

• Understand Dependencies: See exactly which nodes depend on what
• Documentation: Generate visual documentation of data flows
• Code Review: Visual graphs make complex logic easier to review

Breaking Changes

None - this is purely additive functionality with zero external dependencies.

Key Functions:

• graph/extract-graph-structure - Main analysis entry point
• viz/analyze-nodely-env - Analysis + visualization with flexible API modes
• viz/auto-detect-source-file - Reflection-based source file detection