scripts: Add heap snapshot analyzer

Add a script to analyze V8 heap snapshot files (.heapsnapshot) generated
by JETLS's profiling feature. The script parses the snapshot and
displays a summary of memory usage by object type, sorted by shallow
size.

Usage: julia --project=scripts scripts/analyze-heapsnapshot.jl
<snapshot>

Uses binary units (1 KB = 1024 bytes) consistent with macOS and htop.

Written by Claude

Author: aviatesk

DEVELOPMENT.md

@@ -276,6 +276,18 @@ To investigate memory growth:
 
 This helps identify which types are accumulating over time.
 
+### Command-line analysis
+
+For text-based analysis (useful for sharing or automated processing), use the
+`analyze-heapsnapshot.jl` script:
+
+```bash
+julia --project=scripts scripts/analyze-heapsnapshot.jl JETLS_YYYYMMDD_HHMMSS.heapsnapshot
+```
+
+This displays a summary of memory usage by object type, sorted by shallow size.
+Use `--top=N` to control how many entries to show (default: 50).
+
 ### Limitations
 
 - Only Julia GC-managed heap is captured; memory allocated by external libraries

Project.toml

@@ -4,7 +4,7 @@ version = "0.0.0"
 authors = ["Shuhei Kadowaki <aviatesk@gmail.com>"]
 
 [workspace]
-projects = ["docs", "test"]
+projects = ["docs", "test", "scripts"]
 
 [deps]
 Configurations = "5218b696-f38b-4ac9-8b61-a12ec717816d"

scripts/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"

scripts/analyze-heapsnapshot.jl

@@ -0,0 +1,166 @@
+#!/usr/bin/env julia
+
+using JSON3
+using Printf
+
+struct HeapNode
+    type::String
+    name::String
+    id::Int
+    self_size::Int
+    edge_count::Int
+end
+
+struct TypeSummary
+    count::Int
+    shallow_size::Int
+end
+
+function parse_heapsnapshot(path::String)
+    data = open(path) do io
+        JSON3.read(io)
+    end
+
+    snapshot = data["snapshot"]
+    meta = snapshot["meta"]
+    node_fields = meta["node_fields"]
+    node_types = meta["node_types"][1]
+    strings = data["strings"]
+    nodes_array = data["nodes"]
+
+    node_field_count = length(node_fields)
+    node_count = snapshot["node_count"]
+
+    type_idx = findfirst(==("type"), node_fields)
+    name_idx = findfirst(==("name"), node_fields)
+    id_idx = findfirst(==("id"), node_fields)
+    self_size_idx = findfirst(==("self_size"), node_fields)
+    edge_count_idx = findfirst(==("edge_count"), node_fields)
+
+    nodes = Vector{HeapNode}(undef, node_count)
+    for i in 1:node_count
+        base = (i - 1) * node_field_count
+        type_index = nodes_array[base + type_idx] + 1
+        name_index = nodes_array[base + name_idx] + 1
+        node_type = node_types[type_index]
+        node_name = strings[name_index]
+        node_id = nodes_array[base + id_idx]
+        self_size = nodes_array[base + self_size_idx]
+        edge_count = nodes_array[base + edge_count_idx]
+        nodes[i] = HeapNode(node_type, node_name, node_id, self_size, edge_count)
+    end
+
+    return nodes
+end
+
+function summarize_by_type(nodes::Vector{HeapNode})
+    summary = Dict{String,TypeSummary}()
+    for node in nodes
+        key = "($(node.type)) $(node.name)"
+        existing = get(summary, key, TypeSummary(0, 0))
+        summary[key] = TypeSummary(existing.count + 1, existing.shallow_size + node.self_size)
+    end
+    return summary
+end
+
+# Uses binary units (1 KB = 1024 bytes), consistent with macOS and htop.
+# Note: Chrome DevTools uses SI units (1 KB = 1000 bytes), so values will differ slightly.
+function format_size(bytes::Int)
+    if bytes >= 1024 * 1024
+        return @sprintf("%.1f MB", bytes / (1024 * 1024))
+    elseif bytes >= 1024
+        return @sprintf("%.1f KB", bytes / 1024)
+    else
+        return "$bytes B"
+    end
+end
+
+function print_summary(summary::Dict{String,TypeSummary}; top_n::Int=50)
+    sorted = sort(collect(summary); by = x -> x.second.shallow_size, rev = true)
+
+    total_size = sum(s.shallow_size for (_, s) in summary)
+    total_count = sum(s.count for (_, s) in summary)
+
+    wide = 120
+
+    println()
+    println("=" ^ wide)
+    println("HEAP SNAPSHOT SUMMARY")
+    println("=" ^ wide)
+    println()
+    @printf("Total objects: %d\n", total_count)
+    @printf("Total shallow size: %s\n", format_size(total_size))
+    println()
+    println("-" ^ wide)
+    @printf("%-80s %10s %14s %12s\n", "Type/Name", "Count", "Shallow Size", "% of Total")
+    println("-" ^ wide)
+
+    for (i, (key, s)) in enumerate(sorted)
+        i > top_n && break
+        pct = 100.0 * s.shallow_size / total_size
+        display_key = length(key) > 80 ? key[1:77] * "..." : key
+        @printf("%-80s %10d %14s %11.1f%%\n", display_key, s.count, format_size(s.shallow_size), pct)
+    end
+
+    println("-" ^ wide)
+    println()
+end
+
+function print_help()
+    println("""
+    scripts/analyze-heapsnapshot.jl - Heap Snapshot Analyzer
+
+    USAGE:
+        julia scripts/analyze-heapsnapshot.jl <path-to-heapsnapshot> [--top=N]
+
+    DESCRIPTION:
+        Analyzes V8 heap snapshot files (.heapsnapshot) generated by JETLS
+        and displays memory usage summary by object type.
+
+    OPTIONS:
+        --top=N     Show top N entries (default: 50)
+        --help, -h  Show this help message
+
+    EXAMPLE:
+        julia scripts/analyze-heapsnapshot.jl JETLS_20251203_120000.heapsnapshot
+        julia scripts/analyze-heapsnapshot.jl JETLS_20251203_120000.heapsnapshot --top=100
+    """)
+end
+
+function parse_args(args::Vector{String})
+    path = nothing
+    top_n = 50
+
+    for arg in args
+        if arg == "--help" || arg == "-h"
+            print_help()
+            exit(0)
+        elseif startswith(arg, "--top=")
+            top_n = parse(Int, split(arg, "="; limit=2)[2])
+        elseif !startswith(arg, "-")
+            path = arg
+        else
+            @warn "Unknown argument: $arg"
+            println("\nRun with --help for usage information")
+            exit(1)
+        end
+    end
+
+    if path === nothing
+        error("Heap snapshot path is required\nRun with --help for usage information")
+    end
+
+    return (path, top_n)
+end
+
+function (@main)(args::Vector{String})
+    (path, top_n) = parse_args(args)
+
+    if !isfile(path)
+        error("File not found: $path")
+    end
+
+    nodes = parse_heapsnapshot(path)
+    summary = summarize_by_type(nodes)
+    print_summary(summary; top_n)
+end