Say hello to Graph Buddy!

Your new best pal to help you understand your Scala code better

With today’s IDEs, we are all forced to browse code written as text in flatly-structured files, with almost no information about the semantic dependencies between particular code units. What if we could take a different look and, instead of seeing just source code in text files, go through colorful graph nodes that instantly and clearly show you dependencies and other essential structural bits extracted from your codebase?

How can Graph Buddy help you?

Graph Buddy aims to speed up your process of reading and learning about source codes. The Graph Buddy plugin provides a set of useful features and techniques that will help you easily browse through twisted code dependencies. At the same time, it gives you a better understanding of the code structure in your codebase.

How does it work?

During compilation Graph Buddy extracts additional project metadata - Semantic Code Graph files (stored in .semanticgraphs folder). These files are consumed and visualized as an interactive graph in the Graph Buddy plugin.

Graph Buddy User flow


Table of Contents


Supported languages

⚠ Graph Buddy is an experimental project and currently only supports:

Installing and configuring the extension

To make it work, you need to:

  1. Configure your project
  2. Install the plugin in your IDE

Your project configuration

The graph files will be generated during the compilation and stored in .semanticgraphs folder.

Note: You can play around with Graph Buddy using our scala example. Just open this project inside your IDE (IntelliJ or VSCode) with the Graph Buddy plugin installed (available via IDE official marketplace).

Scala configuration

The only requirement is the scalac compiler plugin.

For sbt you can use sbt plugin. Just create plugin file project/graphbuddy.sbt with the content:

resolvers += Resolver.bintrayIvyRepo("virtuslab", "graphbuddy")
addSbtPlugin("com.virtuslab" % "semantic-graphs-sbt-plugin" % "0.2.8")

or add scalac compiler plugin directly:

resolvers += Resolver.bintrayRepo("virtuslab", "graphbuddy")
addCompilerPlugin("com.virtuslab.semanticgraphs" % "scalac-plugin" % "0.2.8" cross CrossVersion.full)
scalacOptions += "-Yrangepos"

Please remember to recompile the project with a new scalac plugin. In sbt:

sbt clean test:compile

Graph Buddy currently supports following scala versions:

TypeScript configuration (experimental support)

Typescript data will be generated based on the project configuration defined in tsconfig.json:

⚠ Currently, you can play with Typescript, but keep in mind that it is still under active development. There is a lot of work yet to be done to cover all currently unhandled cases. We recommend using a Graph Buddy ts-example demonstration repo as a playground.

Installing a plugin

Make sure you have the following installed:

The plugin is available for:

You can install the plugin directly in your IDE - simply navigate to the store inside your IDE and search for Graph Buddy.


How to use Graph Buddy

Graph Buddy plugin adds a unique view into your IDE. You can perform visual operations, both by clicking on your code or on the graph visualization. Doing so will modify the graph structure accordingly, showcasing semantics info about your project.

Opening the Graph Buddy board

IntelliJ

Look for a ‘GraphBuddy’ tab in the bottom right corner and press it.

Graph Buddy User flow

VSCode

Click the GraphBuddy icon in the activity bar (left), then press the Open Graph Buddy window button. It will open the Graph Buddy board; just wait for the reindexing process to finish and start browsing!

Graph Buddy User flow

Indexing the graph

In Intellij and VSCode the graph will be reindexed automatically during the project startup.

To reindex graph manually:

Graph Buddy features

List of functionalities

IDE Side

Code highlight When clicking inside code editor, corresponding nodes and connected to it edges will be highlighted or dynamically added
Code context menu By right-clicking on code, you have an option to render graph for both file and symbol, which will display either full graph per file or all connections for current symbol.
Reindex menu options By clicking 'Reindex graph (*add mode)' in menu bar (IntelliJ) or in left-side panel (VSCode) you index server with newest data with override or *adding to existing data mode
Codelens A codelens (tooltip text) that appears above queries in .sql files in .graphbuddy folder, that allows you to run query and display the result on graph / text
Theming Webview styles change depending on selected IDE theme

Unique to VSCode

Side panel A Graph Buddy icon should exist on the left side panel of vscode
Start extension panel button In plugin panel window a welcome button exists, thats opens up an extension and changes view to advanced options
Main panel options Panel window contains options such as: reindex options, show graph options, open new Graph Buddy window
Advanced query editor Window that contains all .sql files and allows to add, delete, rename; files are located in '/workspace/.graphbuddy' folder

Webview-side

NOTE: The base network mode for features is 2d, some features are not/less available on 3d graph.

Graph canvas

Graph highlighting By clicking on nodes or edges, graph will highlight corresponding nodes and edges
Graph data styles Each data object has its own unique styling
Removing data By shift-clicking node (or choosing option in context menu), you remove it from the webview
Adding data to the graph By double clicking on node you extend the graph by adding data corresponding with clicked node
Data positioning By dragging nodes you position them on the canvas
Info on hover By hovering over node/edge, a popup appears that contains some additional info about targeted data object
Context menu By right clicking on canvas, you open up a context menu with options depending on clicked data: node, edge, data kind or background
Flash messages By performing various actions, flash message will display above interface buttons panel
Filtering options By clicking the buttons in filtering menu, you toggle visibility of corresponding node/edge kind
Layout options By switching layout in the navigation bar (layers icon), you change rendering method of the graph (classic, vertical, horizontal)
Network settings By selecting additional network options, you can adjust graph visibility and amount of visible informations to your liking

Interface buttons

Switch graph mode By clicking switch graph mode button, you change between 2d and 3d network
Freeze graph By clicking freeze graph button, you lock the graph disallowing it to update any data
Force directed graph By clicking force directed graph button, you toggle real-time physics interactions on graph
Reorganise graph By clicking reorganise graph button, you reorganise network nodes positions
Clear graph By clicking clear network data graph button, you clear all existing graph data
Show click history By clicking show history button, you set the graph data to last 10 clicked nodes
Find path modal By clicking find path button, you open up a modal that allows you to find connection and highlight path between selected nodes
Fuzzy search By clicking fuzzy search button (or by pressing ':'), you open up a modal that allows you to search and highlight data based on typed query
Graph file manager By clicking graph file manager button, you open up a modal that allows you to save current graph data snapshot or load it, from a file; default location is /workspace/.graphbuddy

Keyboard shortcuts

Revert action By pressing 'ctrl+z' you revert last action (add/update/remove/re-position)
Close modal By pressing 'esc' you close any modal currently active
Fuzzy search By pressing ':' open fuzzy search modal

Each declaration or definition is represented as a node and the connection between them as an edge. When browsing the code, Graph Buddy will update the graph board interactively. Additionally, by right-clicking in a text editor, you can draw the graph for the whole file unit or for a particular definition.

Graph Buddy User flow

You can perform several interactions on the Graph Buddy board to better understand the code structure. Choose between a range of features like: finding a path between nodes; showing the history of last elements clicked; changing pointing edges direction; filtering by node kind, and many more!

Graph Buddy User flow Graph Buddy User flow Graph Buddy User flow

Advanced queries (very much experimental)

Graph Buddy logic is backed up currently by the OrientDB database. We decided to use this feature to allow users experiment and write custom queries. We believe that it might bring some new interesting feedback and ideas as today’s search options in IDE are usually nothing more than advanced grep. Searching through the graphs let user construct more advanced searches using the power of semantic data and non-trivial node/edge properties or combinations of both.

As an example, let’s say you want to find all the places where some particular library is used in your source code. With graph SQL dialect query, it will simply be:

SELECT FROM E WHERE in IN (SELECT FROM Node WHERE id LIKE "%org\/your\/library%")

or you can narrow down the results to visualize only calls to this library:

SELECT FROM E WHERE in IN (SELECT FROM Node WHERE id LIKE "%org\/your\/library%") AND @class = "CALL"

Advanced queries tree view (VSCode)

  1. Advanced queries tree view allows you to write custom queries in the SQL language.
  2. Via code lenses in Graph Buddy .sql file you can run the query. The result is presented as graph visualization or in a JSON file.
  3. Advanced queries editor saves query files locally in .graphbuddy folder and you can manage them (create/rename/delete) directly from the editor.

Roadmap

Released

Planned


Contact us

We are happy to get constructive feedback that could improve this project! If you want to help/ask questions, feel free to contact us: [email protected]