Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add mermaid.js for diagrams #26

Open
jasonwilliams opened this issue Mar 9, 2022 · 0 comments
Open

add mermaid.js for diagrams #26

jasonwilliams opened this issue Mar 9, 2022 · 0 comments

Comments

@jasonwilliams
Copy link
Member

https://mermaid-js.github.io/mermaid/#/
@HalidOdat HalidOdat mentioned this issue Nov 8, 2022
Closed
10 tasks
bors bot pushed a commit to boa-dev/boa that referenced this issue Nov 22, 2022
@HalidOdat
Implement instruction flowgraph generator (#2422)
a2964e6 
This PR is a WIP implementation of a vm instruction flowgraph generator

This aims to make the vm easier to debug and understand for both newcomers and experienced devs.

For example if we have the following code:
```js
let i = 0;
while (i < 10) {
    if (i == 3) {
        break;
    }
    i++;
}
```
It generates the following instructions (which is hard to read, especially jumps):
<details>

```
----------------------Compiled Output: '<main>'-----------------------
Location  Count   Opcode                     Operands

000000    0000    PushZero
000001    0001    DefInitLet                 0000: 'i'
000006    0002    LoopStart
000007    0003    LoopContinue
000008    0004    GetName                    0000: 'i'
000013    0005    PushInt8                   10
000015    0006    LessThan
000016    0007    JumpIfFalse                78
000021    0008    PushDeclarativeEnvironment 0, 1
000030    0009    GetName                    0000: 'i'
000035    0010    PushInt8                   3
000037    0011    Eq
000038    0012    JumpIfFalse                58
000043    0013    PushDeclarativeEnvironment 0, 0
000052    0014    Jump                       78
000057    0015    PopEnvironment
000058    0016    GetName                    0000: 'i'
000063    0017    IncPost
000064    0018    RotateRight                2
000066    0019    SetName                    0000: 'i'
000071    0020    Pop
000072    0021    PopEnvironment
000073    0022    Jump                       7
000078    0023    LoopEnd

Literals:
    <empty>

Bindings:
    0000: i

Functions:
    <empty>
```

</details>

And the flow graph is generated:
![flowgraph](https://user-images.githubusercontent.com/8566042/200589387-40b36ad7-d2f2-4918-a3e4-5a8fa5eee89b.png)

The beginning of the function is  marked by the `start` node (in green) and end (in red). In branching the "yes" branch is marked  in green and "no" in red.

~~This only generates in [graphviz format](https://en.wikipedia.org/wiki/DOT_(graph_description_language)) (a widely used format) but it would be nice to also generate to a format that `mermaid.js` can understand and that could be put in articles boa-dev/boa-dev.github.io#26

TODO:
  - [x] Generate graphviz format
  - [x] Generate mermaid format
  - [x] Programmatically generate colors push and pop env instructions
  - [x] Display nested functions in sub-sub-graphs.
  - [x] Put under a feature (`"flowgraph"`)
  - [x] Handle try/catch, switch instructions
  - [x] CLI option for configuring direction of flow (by default it is top down)
  - [x] Handle `Throw` instruction (requires keeping track of try blocks)
  - [x] Documentation
  - [x] Prevent node name collisions (functions with the same name)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@jasonwilliams