feat(cli): Visualize the Control Flow Graph

[aakoshh]

Description

Problem*

Resolves a follow up for #9826

Summary*

Adds a visualize command to the SSA CLI which renders the CFG as a Mermaid flowchart.

Example

Take this Noir program:

fn main(a: bool) {
    if a {
        for i in 0..5 {
            foo(i);
        }
    }
}

fn foo(i: u32) {
    if i < 3 {
        println(f"cold {i}");
    } else {
        println(f"hot {i}");
    }
}

Render it with Mermaid using the --markdown option to get a file we can preview in VS Code or include on Github:

cargo run -q -p nargo_cli -- compile --silence-warnings --show-ssa-pass Initial \
  | tail -n +2 \
  | cargo run -q -p noir_ssa_cli -- visualize --markdown \
  > test.md

Open test.md in VSCode in Preview mode (requires the Mermaid Markdown extension):

Alternatively use the --url-encode option to construct a URL that can be used with the Mermaid Live editor:

open https://mermaid.live/view#$( \
  cargo run -q -p nargo_cli -- compile --silence-warnings --show-ssa-pass Initial \
    | tail -n +2 \
    | cargo run -q -p noir_ssa_cli -- visualize --url-encode)

(The tail gets rid of the After Initial SSA: message printed by nargo, which the SSA parser doesn't handle. We could change this to a comment, if nobody relies on it being this particular way).

In this example it opens this URL.

When working in the context of a nargo project, we can visualize an SSA pass using the following helper command:

just visualize-ssa-cfg Initial

Note that the SSA pass name must be unique for this to work.

Additional Context

I added a FunctionView wrapper for Function so that we don't have to pollute its API with a random selection of pub functions, because most things are pub(crate) only.

Documentation*

Check one:

• No documentation needed.
• Documentation included in this PR.
• [For Experimental Features] Documentation to be submitted in a separate PR.

PR Checklist*

• I have tested the changes locally.
• I have formatted the changes with Prettier and/or cargo fmt on default settings.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Test Suite Duration'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: 0d3ca4c	Previous: 05a61db	Ratio
test_report_zkpassport_noir_rsa_	2 s	1 s	2

This comment was automatically generated by workflow using github-action-benchmark.

CC: @TomAFrench

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Execution Time'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: aafd37f	Previous: be751f0	Ratio
rollup-merge	0.003 s	0.002 s	1.50
rollup-root	0.005 s	0.004 s	1.25

This comment was automatically generated by workflow using github-action-benchmark.

CC: @TomAFrench

[TomAFrench]

Nice! this is really cool and something I've been wishing for when working with some of the CFG related passes!

[aakoshh]

I thought it would be cool to have options to highlight the Post-Dominance-Frontier of a block for example.
It would probably awkward to do that in the CLI, but imagine if we had an LSP for the SSA to support hand editing it, with some right click menu to help with that 🤓

[jfecher]

cargo run -q -p nargo_cli -- compile --silence-warnings --show-ssa-pass Initial
| tail -n +2
| cargo run -q -p noir_ssa_cli -- visualize --markdown
test.md

What is the purpose of the first two lines here? We're compiling the program first, then using tail for something, then using the visualize command? Can we use the visualize command on its own?

If not, lets add this to the justfile so team members won't need to reconstruct this command each time.

[aakoshh]

What is the purpose of the first two lines here?

Basically just getting rid of the After Initial SSA: line.

We're compiling the program first,

Yes, we're using nargo compile to get the SSA of a Noir program. We could be copying the SSA from a unit test, or from the terminal instead if that was the use case.

then using tail for something,

The SSA CLI treats input as something that can be parsed. The SSA parser handles comments, but doesn't expect the After ... messages that nargo uses to print stuff. When the SSA CLI itself prints SSA for logging purposes, it prints the message as After as well, but in the output itself it appears as // After, so we can parse it back, while still being reminded what it was.

I didn't want to touch nargo, but I suppose we could just print // there as well. (Or filter After in the CLI, but I thought that's ugly, whereas the scripting can be a sin-bin).

then using the visualize command?

Yes, it reads the SSA from stdin in this case.

Can we use the visualize command on its own?

You can use it on its own with --source-path if you have an SSA in a file, or pbpaste if you copied from a unit test.

There is no visualize command in nargo, so "on its own" doesn't work that way. Ostensibly we could add it, but I'm not sure it meshes well.

If not, lets add this to the justfile so team members won't need to reconstruct this command each time.

I thought people would come up with their own scripting depending on what they find most useful (e.g. local vs live editor), but I'll have a look where it could go 👍

[aakoshh]

Added a just visualize <pass> command, only handling the blue sky scenario of no errors and a unique SSA pass matched by name.

[jfecher]

Added a just visualize command, only handling the blue sky scenario of no errors and a unique SSA pass matched by name.

Can you rename it to just visualize_cfg <pass> or even just visualize_ssa_cfg <pass>? In the context of noir_ssa_cli it is more clear it refers to something in the ssa but for the project as a whole visualize alone sounds very broad.

[TomAFrench]

LGTM

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​web/​dev-server-import-maps@​0.2.1
	@​web/​dev-server-esbuild@​1.0.4
	@​web/​test-runner-playwright@​0.11.1
	@​types/​adm-zip@​0.5.7
	buffer-esm@​1.2.0
	toml@​3.0.0
	@​ltd/​j-toml@​1.38.0
	tslog@​4.9.3
	@​nomicfoundation/​hardhat-chai-matchers@​2.1.0
	@​esm-bundle/​chai@​4.3.4
	ethers@​6.15.0
	smol-toml@​1.4.2
	@​web/​test-runner@​0.20.2
	hardhat@​2.26.3
	@​nomicfoundation/​hardhat-ethers@​3.1.0

View full report