DunneFlow · Tutorial

Ask questions from the command line

Use touches, impact, glossary, naming, mirror and query to get answers about a map without opening a browser.

Available15 min· Intermediate· DunneFlow 0.2.0

The dashboard is one reader for a map; the terminal is another. In this tutorial you ask six questions of an existing map from the command line: what a routine reaches, what depends on it, what the program's words mean, how its names are spelled, what its documents define that its code never uses, and anything else, in SQL.

You'll need#

A finished map. The examples use the dunneflow map from Map DunneFlow with DunneFlow; substitute your own program name and routine names.
A terminal in the directory you analysed from (for a source checkout, the checkout). With the application, use its command-line program and add --output pointing at your maps folder.

Steps#

Learn how a command finds its map.
```
uv run dunneflow touches output/dunneflow --routine cmd_analyze
```
The first line reads no --output given; maps go to output. The path you give these commands names a program: DunneFlow takes its last segment, dunneflow, and looks for it under the maps root. So touches dunneflow --output output finds the same map.
Ask what a routine reaches. Read the output of step 1: the routine and its location, how many routines it reaches, then every boundary any of them touches, grouped by kind (DATABASE, ENV, FILE, STDIO…) and quoted as written. --routine takes a plain or qualified name; if a plain name matches several routines, each is reported, up to --limit (default 5).
Ask what breaks if you change it.
```
uv run dunneflow impact output/dunneflow --routine write_file_facts
```
impact walks the graph backwards: how many routines depend on this one, and which ways in would be affected. That second list is the question worth asking before you touch anything.
Ask what the words mean.
```
uv run dunneflow glossary output/dunneflow
```
It reports how many of the program's terms are defined anywhere, and for each defined term its definition, the kind of source, and the file and line that prove it.
Ask how names are spelled.
```
uv run dunneflow naming output/dunneflow
```
STATED quotes any naming rules the documentation writes down (it may say none are stated). MEASURED counts conventions the code actually follows, each with how many exceptions it has.
Ask what the documents define that the code never uses.
```
uv run dunneflow mirror output/dunneflow
```
Terms fall into four bands: Named, Borne, Spoken and Absent. Absent terms are defined in the documentation and never used in the code, the strongest sign of drift.
Ask the graph anything.
```
uv run dunneflow query output/dunneflow \
    --sql "SELECT kind, COUNT(*) n FROM boundaries GROUP BY kind ORDER BY n DESC"
```
This reproduces the cover's What it touches panel in a terminal. The graph's tables include routines, calls, boundaries, files, constants, comments and sql_ops. query is read-only.
Run a dashboard query yourself. In the dashboard, open Explore → Worth a look, press show the query on any card, and paste the statement into --sql. It returns exactly what the card showed.

What you've learned#

The path you give a question command names a program under the maps root.
touches runs the graph forwards and impact runs it backwards to the ways in.
glossary, naming and mirror answer questions about the program's vocabulary.
query is the read-only escape hatch, and every show the query statement runs in it.

Next#

Something unclear or out of date? Tell us.

You'll need#

A finished map. The examples use the dunneflow map from Map DunneFlow with DunneFlow; substitute your own program name and routine names.

A terminal in the directory you analysed from (for a source checkout, the checkout). With the application, use its command-line program and add --output pointing at your maps folder.

Steps#

Learn how a command finds its map.
```
uv run dunneflow touches output/dunneflow --routine cmd_analyze
```
The first line reads no --output given; maps go to output. The path you give these commands names a program: DunneFlow takes its last segment, dunneflow, and looks for it under the maps root. So touches dunneflow --output output finds the same map.
Ask what a routine reaches. Read the output of step 1: the routine and its location, how many routines it reaches, then every boundary any of them touches, grouped by kind (DATABASE, ENV, FILE, STDIO…) and quoted as written. --routine takes a plain or qualified name; if a plain name matches several routines, each is reported, up to --limit (default 5).
Ask what breaks if you change it.
```
uv run dunneflow impact output/dunneflow --routine write_file_facts
```
impact walks the graph backwards: how many routines depend on this one, and which ways in would be affected. That second list is the question worth asking before you touch anything.
Ask what the words mean.
```
uv run dunneflow glossary output/dunneflow
```
It reports how many of the program's terms are defined anywhere, and for each defined term its definition, the kind of source, and the file and line that prove it.
Ask how names are spelled.
```
uv run dunneflow naming output/dunneflow
```
STATED quotes any naming rules the documentation writes down (it may say none are stated). MEASURED counts conventions the code actually follows, each with how many exceptions it has.
Ask what the documents define that the code never uses.
```
uv run dunneflow mirror output/dunneflow
```
Terms fall into four bands: Named, Borne, Spoken and Absent. Absent terms are defined in the documentation and never used in the code, the strongest sign of drift.
Ask the graph anything.
```
uv run dunneflow query output/dunneflow \
    --sql "SELECT kind, COUNT(*) n FROM boundaries GROUP BY kind ORDER BY n DESC"
```
This reproduces the cover's What it touches panel in a terminal. The graph's tables include routines, calls, boundaries, files, constants, comments and sql_ops. query is read-only.
Run a dashboard query yourself. In the dashboard, open Explore → Worth a look, press show the query on any card, and paste the statement into --sql. It returns exactly what the card showed.

What you've learned#

The path you give a question command names a program under the maps root.

touches runs the graph forwards and impact runs it backwards to the ways in.

glossary, naming and mirror answer questions about the program's vocabulary.

query is the read-only escape hatch, and every show the query statement runs in it.