dot-viewer in TUI

.cargo/config.toml

@@ -0,0 +1,2 @@
+[target.aarch-apple-darwin]
+rustflags = ["-C", "link-args=-L/opt/homebrew/lib"]

.gitignore

@@ -0,0 +1,6 @@
+Cargo.lock
+/logs
+/target
+.DS_STORE
+*.dot
+*.log

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "dot-graph"]
+	path = dot-graph
+	url = https://github.com/furiosa-ai/dot-graph.git
+  branch = main 

Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "dot-viewer"
+version = "0.1.0"
+authors = ["FuriosaAI, Inc."]
+description = "A viewer/debugger for large DAGs in Vim-like TUI"
+readme = "README.md"
+keywords = ["graph", "dag", "dot", "visualize", "tui"]
+license = "MIT"
+repository = "https://github.com/furiosa-ai/dot-viewer"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+dot-graph = { path = "dot-graph" }
+tui = "0.19.0"
+tui-tree-widget = "0.11.0"
+crossterm = "0.25"
+clap = { version = "4.1.1", features = ["derive"] }
+trie-rs = "0.1.1"
+fuzzy-matcher = "0.3.7"
+html_parser = "0.6.3"
+thiserror = "1.0.38"
+regex = "1.7.1"
+rayon = "1.6.1"
+better-panic = "0.3.0"
+log = "0.4.17"
+simplelog = "0.12.0"
+chrono = "0.4.23"

README.md

@@ -0,0 +1,158 @@
+# dot-viewer
+
+`dot-viewer` is a dot-format graph debugger in TUI, inspired by Vim.
+
+# 1. Getting Started
+
+## a. Prerequisites
+
+### i. Graphviz
+
+`dot-viewer` parses a dot format file using C bindings to [Graphviz (v7.0.6)](https://gitlab.com/graphviz/graphviz/-/tree/7.0.6/lib).
+
+The system environment should be able to find and include the following header files.
+
+```C
+#include <gvc.h>
+#include <cgraph.h>
+```
+
+#### Option 1. Installing Graphviz from Package Manager
+
+Coming from Linux,
+```console
+$ sudo apt install graphviz-dev
+```
+
+And coming from vanilla Ubuntu, you may want to install these too.
+```console
+$ sudo apt install build-essentials cmake
+$ sudo apt install clang
+```
+
+Coming from Mac,
+```console
+$ brew install graphviz
+```
+
+And coming from Apple Silicon Mac, and [add an environment variable](https://apple.stackexchange.com/questions/414622/installing-a-c-c-library-with-homebrew-on-m1-macs),
+```shell
+export CPATH=/opt/homebrew/include
+```
+
+#### Option 2. Building Graphviz from Source
+
+Or, try building from the source code following the [guide](https://graphviz.org/download/source/).
+
+### ii. xdot.py
+
+`dot-viewer` renders a subgraph with `xdot.py`, an interactive dot visualizer.
+
+It is required that [xdot is executable in command-line](https://github.com/jrfonseca/xdot.py) beforehand such that the following works.
+```console
+$ xdot *.dot
+```
+
+## b. Installation
+
+### i. Initialize
+
+First initialize and update the submodule `dot-graph`.
+
+```console
+$ git submodule init
+$ git submodule update
+```
+
+### ii. Run
+
+Then run crate.
+
+```console
+$ cargo run --release [path-to-dot-file]
+```
+
+This will open a TUI screen on the terminal.
+
+# 2. Features
+
+With `dot-viewer`, users may
+
+**traverse the graph in TUI** using,
+- goto next/prev node of the currently selected node
+- fuzzy search on node name
+- regex search on node name and attributes
+
+
+**make and export subgraphs** using,
+- subgraph tree selection
+- applying filter on search matches
+- neighboring `n` nodes of the currently selected node
+
+## Keybindings
+
+### General
+
+Key | Command | Actions
+--- | --- | ---
+`q` | | quit `dot-viewer`
+ &nbsp; | `:help<CR>` | show help
+`esc` | &nbsp; | go back to the main screen
+
+### Mode Switches
+
+Key | From | To
+--- | --- | ---
+`esc` | All | Normal
+`/` | Normal | Fuzzy Search
+`r` | Normal | Regex Search
+`:` | Normal | Command
+
+### Normal
+
+Key | Actions
+--- | ---
+`c` | close the current tab(view)
+`h/l` | move focus between current, prevs, nexts list
+`j/k` | traverse in focused list
+`n/N` | move between matched nodes
+`gg` | move to the topmost node in focused list
+`G` | move to the bottom node in focused list
+`tab`/`backtab` | move between tabs
+
+### Search
+Key | Actions
+--- | ---
+`tab` | autocomplete search keyword
+`enter` | apply search
+
+e.g., in fuzzy search mode, `/g1_s14_t100` and in regex search mode, `r\(H: ., D: .\)`
+
+### Command
+
+Key | Command | Actions
+--- | --- | ---
+&nbsp; | `filter` | apply filter on current matches, opening a new tab(view)
+&nbsp; | `neighbors [depth]` | get up to `depth` neighbors of the current node in a new tab(view)
+&nbsp; | `export [(opt) filename]` | export the current tab(view) to dot
+&nbsp; | `xdot [(opt) filename]` | launch `xdot` with the filename or `exports/current.dot` by default
+&nbsp; | `subgraph` | open a popup showing subgraph tree
+`tab` | &nbsp; | autocomplete command
+`enter` | &nbsp; | execute command
+
+All exported files are saved in `exports` directory in the project root.
+
+Most recently exported file is copied in `exports/current.dot`.
+
+### Subgraph Popup
+
+Key | Actions
+--- | ---
+`h/j/k/l` | traverse the tree
+`enter` | change root to the selected subgraph, opening a new tab(view)
+
+### Help Popup
+
+Key | Actions
+--- | ---
+`h/j/k/l` | traverse help messages

rustfmt.toml

@@ -0,0 +1,4 @@
+edition = "2021"
+
+# https://github.com/rust-lang/rustfmt/blob/master/Configurations.md#use_small_heuristics
+use_small_heuristics = "Max"

src/main.rs

@@ -0,0 +1,29 @@
+mod terminal;
+mod ui;
+mod viewer;
+
+use std::error::Error;
+use std::fs;
+
+use chrono::prelude::*;
+use clap::Parser;
+use simplelog::{Config, LevelFilter, WriteLogger};
+
+use terminal::launch;
+
+#[derive(Parser, Default, Debug)]
+struct Cli {
+    path: String,
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let args = Cli::parse();
+
+    fs::create_dir_all("./logs")?;
+    let file = fs::File::create(format!("logs/log_{}.log", Local::now()))?;
+    WriteLogger::init(LevelFilter::Info, Config::default(), file)?;
+
+    launch(args.path)?;
+
+    Ok(())
+}

src/terminal.rs

@@ -0,0 +1,81 @@
+use crate::{ui, viewer::App};
+
+use std::io::Stdout;
+use std::{error::Error, io};
+
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use log::error;
+use tui::{
+    backend::{Backend, CrosstermBackend},
+    Terminal,
+};
+
+pub fn launch(path: String) -> Result<(), Box<dyn Error>> {
+    // setup terminal
+    let mut terminal = setup()?;
+
+    // create and run app
+    let app = App::new(&path).map_err(|_| {
+        let _ = cleanup();
+
+        Box::<dyn Error>::from("user should provide path to a valid dot file")
+    })?;
+    let _ = run(&mut terminal, app);
+
+    // restore terminal
+    cleanup()?;
+
+    Ok(())
+}
+
+fn setup() -> Result<Terminal<CrosstermBackend<Stdout>>, Box<dyn Error>> {
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let terminal = Terminal::new(backend)?;
+
+    // setup panic hook to ensure that the terminal is restored even on panics
+    setup_panic_hook();
+
+    Ok(terminal)
+}
+
+fn setup_panic_hook() {
+    let panic_handler = better_panic::Settings::auto().create_panic_handler();
+    std::panic::set_hook(Box::new(move |info| {
+        let _ = cleanup();
+
+        error!("dot-viewer {}", info);
+
+        panic_handler(info);
+    }));
+}
+
+fn run<B: Backend>(terminal: &mut Terminal<B>, mut app: App) -> io::Result<()> {
+    loop {
+        terminal.draw(|f| ui::draw_app(f, &mut app))?;
+
+        if let Event::Key(key) = event::read()? {
+            app.key(key);
+        }
+
+        if app.quit {
+            break;
+        }
+    }
+
+    Ok(())
+}
+
+fn cleanup() -> Result<(), Box<dyn Error>> {
+    let mut stdout = io::stdout();
+    execute!(stdout, LeaveAlternateScreen, DisableMouseCapture)?;
+    disable_raw_mode()?;
+
+    Ok(())
+}

src/ui/app.rs

@@ -0,0 +1,36 @@
+use crate::ui::{input::draw_input, popup::draw_popup, tabs::draw_tabs};
+use crate::viewer::{App, Mode};
+
+use tui::{
+    backend::Backend,
+    layout::{Alignment, Constraint, Direction, Layout, Rect},
+    widgets::{Block, BorderType, Borders},
+    Frame,
+};
+
+pub(crate) fn draw_app<B: Backend>(f: &mut Frame<B>, app: &mut App) {
+    let size = f.size();
+
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .title("Dot-Viewer (v0.1.0)")
+        .title_alignment(Alignment::Center)
+        .border_type(BorderType::Rounded);
+
+    f.render_widget(block, size);
+
+    match &app.mode {
+        Mode::Normal | Mode::Command | Mode::Search(_) => draw_main(f, size, app),
+        Mode::Popup(_) => draw_popup(f, size, app),
+    }
+}
+
+fn draw_main<B: Backend>(f: &mut Frame<B>, size: Rect, app: &mut App) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Percentage(90), Constraint::Percentage(10)].as_ref())
+        .split(size);
+
+    draw_tabs(f, chunks[0], app);
+    draw_input(f, chunks[1], app);
+}