DunneFlow · Tutorial

Map DunneFlow with DunneFlow

Run DunneFlow from source, point it at its own code, and explore the result, including the refusal you meet first.

In progress20 min· Intermediate· DunneFlow 0.2.0

The quickest way to learn DunneFlow on a real program is to point it at itself. In this tutorial you run DunneFlow from a source checkout, analyse its own src/dunneflow directory, and walk the result. Because the program is DunneFlow, you can check what the map tells you against what you already know about the tool.

You'll need#

Python 3.12 or newer, and uv.
A clone of the DunneFlow repository on GitHub.
Node.js 20 or newer, because DunneFlow's own source includes some TypeScript. Without it, add --without typescript in step 3.

Steps#

Clone and set up the source.

git clone https://github.com/aacloudguy/dunneflow.git dunneflow
cd dunneflow
uv sync

Check that it runs.
```
uv run dunneflow --help
```
You should see the list of commands.
Analyse DunneFlow's own source.
```
uv run dunneflow analyze src/dunneflow --name dunneflow
```
The map is written to output/dunneflow. The first line says so (no --output given; maps go to output). The run ends with a summary: how many files it read per language, what it left unread, and which directories it pruned.
Open the dashboard.
```
uv run dunneflow serve output/dunneflow
```
Your browser opens on the map's cover. Leave this terminal running.
Read the cover. Where to start shows the command-line entry point commanding most of the program, with the web server hanging off to one side. What it touches is dominated by DATABASE and FILE, as you would expect from a tool built on SQLite. Click NETWORK: every entry is local, such as finding a free port. That row is how you can check the claim that nothing leaves your machine.
Meet the first refusal. Open the program menu, choose + Analyse a directory…, and enter the full path to the same src/dunneflow directory. Call it fills in with dunneflow, and the dialog refuses: dunneflow is the program being read. Analysing into the map you are reading could empty it under you. Press Cancel. (Running analyze from a second terminal, as in step 3, is the other way round it.)
Find one routine. Press /, type cmd_serve, and pick the routine. Look at the inspector: TOUCHES lists the SQL, environment variables and files the server start-up touches.
Read it six ways. With cmd_serve selected, switch the centre through Graph, Table, Document, Code, Diagram and Shape. Each shows the same selection. In Code, click an underlined call to move to the routine it resolves to.
Open the worklist. Click Suspect under What looks wrong, and read a finding's blind spot, then Info. Some findings may turn out to be limitations of DunneFlow rather than problems in the program (a name in a SQL statement that is not really a table, for instance). That is what the 3 key, a defect in DunneFlow, is for.
Stop the server with Ctrl+C in the terminal when you are done.

What you've learned#

How to run DunneFlow from source with uv sync and uv run.
How analyze and serve fit together, and where a source checkout writes its maps.
Why the dashboard refuses to analyse into the map it is serving.
How to check DunneFlow's local-only claim on its own map.

Next#

Compare two versions: seal this map and compare it with an older checkout.
Ask questions from the command line.
Reference: Installing.

Something unclear or out of date? Tell us.

Steps#

Clone and set up the source.

git clone https://github.com/aacloudguy/dunneflow.git dunneflow
cd dunneflow
uv sync

Check that it runs.
```
uv run dunneflow --help
```
You should see the list of commands.
Analyse DunneFlow's own source.
```
uv run dunneflow analyze src/dunneflow --name dunneflow
```
The map is written to output/dunneflow. The first line says so (no --output given; maps go to output). The run ends with a summary: how many files it read per language, what it left unread, and which directories it pruned.
Open the dashboard.
```
uv run dunneflow serve output/dunneflow
```
Your browser opens on the map's cover. Leave this terminal running.
Read the cover. Where to start shows the command-line entry point commanding most of the program, with the web server hanging off to one side. What it touches is dominated by DATABASE and FILE, as you would expect from a tool built on SQLite. Click NETWORK: every entry is local, such as finding a free port. That row is how you can check the claim that nothing leaves your machine.
Meet the first refusal. Open the program menu, choose + Analyse a directory…, and enter the full path to the same src/dunneflow directory. Call it fills in with dunneflow, and the dialog refuses: dunneflow is the program being read. Analysing into the map you are reading could empty it under you. Press Cancel. (Running analyze from a second terminal, as in step 3, is the other way round it.)
Find one routine. Press /, type cmd_serve, and pick the routine. Look at the inspector: TOUCHES lists the SQL, environment variables and files the server start-up touches.
Read it six ways. With cmd_serve selected, switch the centre through Graph, Table, Document, Code, Diagram and Shape. Each shows the same selection. In Code, click an underlined call to move to the routine it resolves to.
Open the worklist. Click Suspect under What looks wrong, and read a finding's blind spot, then Info. Some findings may turn out to be limitations of DunneFlow rather than problems in the program (a name in a SQL statement that is not really a table, for instance). That is what the 3 key, a defect in DunneFlow, is for.
Stop the server with Ctrl+C in the terminal when you are done.