Contact
Back to Insights

Sirens Call is a Python-powered static analysis tool for JavaScript/Node.js CLI projects that generates interactive Mermaid.js flowcharts, helping you visualise execution paths, identify entry points, and gain insight into complex CLI behaviours.

8/05/2025 Article

An evil Siren (Mermaid) enchanting code functions
BG

If you’ve ever tried to reverse engineer a tangled Node.js CLI project, you’ll know just how elusive clarity can be—especially when Commander.js is involved and the entry points are split across a maze of files. That was the pain point that led to the creation of sirens_call: a CLI-first tool that transforms JavaScript project structure into Mermaid.js flowcharts.

TL;DR

  • ✅ CLI tool to visualise JavaScript/Node.js function call flow as Mermaid.js diagrams
  • 📦 Designed for Commander.js CLI apps, supports .js and .mjs files
  • 🧠 Highlights internal vs third-party code, detects entry points
  • 🌐 Outputs .mermaid files and optional HTML previews
  • ⚙️ Built in Python with Tree-sitter for AST parsing, pipenv-based install

Grab the code

https://github.com/yg-ht/sirens_call/

What is Mermaid and “Graph as Code”?

Mermaid is a JavaScript-based diagramming and charting tool that lets you define flowcharts and diagrams using plain text syntax. It supports a wide array of diagram types—from flowcharts to Gantt charts—and integrates seamlessly with Markdown, static site generators, and developer tooling.

This idea of “Graph as Code” is part of a growing movement to bring diagrams into version-controlled environments. Instead of dragging shapes in GUI tools, you define nodes, edges, and relationships in declarative syntax. That means diffs, pull requests, CI validation, and automated documentation pipelines all become possible.

In the context of CLI reverse engineering and static code review, this is especially powerful: you can audit execution paths, track how user input flows through logic, and share insights visually—all without needing to boot the code.

Why This Exists

There’s no shortage of tools for static analysis, but I couldn’t find anything that:

  • Parsed modern JavaScript and .mjs files reliably
  • Detected CLI entry points declared with Commander.js
  • Emitted Mermaid syntax, suitable for integration with markdown, docs-as-code pipelines, and in-browser previews
  • Was happy to run entirely from the CLI in a pipenv

So I built one.

  1. It was designed to help during a project where deep static analysis was needed but runtime behaviour wasn’t accessible. Once the project wrapped, the tool was still useful enough to publish rather than let it rot on a private repo.

How It Works

Sirens Call performs a two-pass traversal of your JS/MJS codebase using Tree-sitter’s Abstract Syntax Tree (AST):

  • First pass – function declarations are indexed and deduplicated
  • Second pass – function calls, including Commander’s .command(…).action(…) chains, are resolved into an execution graph

Entry points are identified and treated as roots in a Breadth-First Search (BFS) traversal, and a layered Mermaid flowchart is generated for each one. External functions (like those in imported modules) are visually marked. There’s even limited loop-awareness for annotating repetitive calls.

This is a rendered mermaid graph showing the execution flow and function calls for an example piece of code

Features at a Glance

  • ✅ AST-driven two-pass analysis using Tree-sitter
  • 🎯 Detects Commander-style CLI commands as distinct execution entry points
  • 🧠 Differentiates internal project code from node_modules or third-party cruft
  • 📊 Outputs .mermaid** files** and (optionally) full HTML previews
  • 🔍 Built-in –verbose debug mode and –debug-graph fallback rendering
  • 🖥️ CLI-native: designed for use in pipelines, CI, or local recon workflows

Caveats & Known Issues

  • Loop rendering is intentionally conservative and sometimes over-squashes
  • Call depth layout isn’t always vertically neat—edge reuse can bend things
  • There’s no styling distinction for return vs invoke paths (yet)
  • It’s not “production-grade”—more of a working research tool

Future Directions

  • sirens_call was built to scratch an itch—not as a full-time product. However:
  • Pull requests are welcome
  • There’s potential to adapt it to other Tree-sitter-supported languages
  • If you’re using it in wild ways (e.g., for supply chain audits, training, or graphviz conversion), I’d love to hear from you

Get in touch