Bicep visualizer #2357

shenglol · 2021-04-22T02:17:43Z

Not something we planned, but I've been working on implementing this for a while as a side project during my spare time, and it finally gets to a point where I can submit a PR.

Main features:

Fault-tolerant resource dependency graph rendering
Beautiful layout
Error highlighting
Live update

To try it out:

Check out this branch
Under root, run dotnet build
cd ./src/vscode-bicep
npm i
code .
Press CTRL + F5 to launch a new window of VSCode
Open a Bicep file
Click the icon shown below at the top-right corner

Demos:

Closes #2358.
Closes #2290

shenglol · 2021-04-22T02:29:18Z

src/vscode-bicep/webpack.config.ts

+    rules: [
+      {
+        test: /\.ts$/,
+        loader: "esbuild-loader",


Replacing ts-loader with esbuild-loader reduces by half the bundling time. For now we want to keep webpack because we need the plugins, but I'll investigate replacing it completely with esbuild (which is about 100x faster).

src/vscode-bicep/package.json

shenglol · 2021-04-22T02:45:03Z

src/vscode-bicep/src/visualizer/app/assets/icons/graph/module.svg

+    <polygon fill="#FFD289" points="64.11,71.99 64.04,98.07 41.33,84.97 41.41,58.88"/>
+    <polygon fill="#FFF1DC" points="86.67,58.88 64.11,71.99 41.41,58.88 63.96,45.77"/>
+  </g>
+</svg>


The two icons are created by me to avoid license issues.

I was thinking about using the official Azure architecture icons, but there is Terms of Use for those icons, which might affect our license. We'll need to figure it out later.

Can we access the VS code icons somehow? Could be an alternative?

We could also get new icons designed specifically for the Bicep visualizer.

No, we cannot access VS code icons inside a webview, plus VS code doesn't provide icons for ARM providers and resources. AFAIK there's no good alternative for Azure icons, besides, I think we should probably not use something not official to represent MS products. As for designing our own icons, we can definitely do that for general UI icons, but it might not be practical to do it for so many RPs and resources.

I've attached the the terms of use of the Azure architecture icons, which I think won't block us from using it in a resource dependency graph (still need to confirm with their team).

However, my real concern is that no matter what SVG files we check in, they will become open source under MIT license. The office team seems to have the same issue with their fluentui repo, and their solution is to add a supplementary assets license agreement to the README license section, so maybe we can do the same thing. Thoughts?

Architecture icons seem like a reasonable option. My suggestion for designing new ones was only about replacements for the ones you did yourself. I definitely wouldn't want us to try to create 100s of RP icons.

MarcusFelling · 2021-04-22T02:55:46Z

👏

src/Bicep.Core/Emit/ResourceDependencyVisitor.cs

src/Bicep.LangServer/Handlers/BicepDeploymentGraphHandler.cs

majastrz · 2021-04-22T03:49:04Z

src/Bicep.LangServer/Handlers/BicepDeploymentGraphHandler.cs

+    [Method("textDocument/deploymentGraph", Direction.ClientToServer)]
+    public record BicepDeploymentGraphParams(TextDocumentIdentifier TextDocument) : ITextDocumentIdentifierParams, IRequest<BicepDeploymentGraph?>;
+
+    public record BicepDeploymentGraph(IEnumerable<BicepDeploymentGraphNode> Nodes, IEnumerable<BicepDeploymentGraphEdge> Edges, int ErrorCount);


record

Ooh records!

anthony-c-martin · 2021-04-26T14:37:01Z

src/vscode-bicep/src/visualizer/app/components/Graph/style.ts

+  type = type.split("/").pop() ?? type;
+  type += isCollection ? "[]" : "";
+
+  const backgroundSvg = `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE svg>


Why not just use tsx here? Wouldn't that remove the need for manual xml escaping?

Because we are using a vanilla JS library (cytoscape.js) to render the graph and this is the way to set custom SVG background for nodes.

PS: we are using cytoscape because it is capable of rendering compound/nested graph. Eventually I would like to drop the dependency on cytoscape and implement our own graph renderer as a React component, but that's something we can do in the future as it requires quite a lot of work (or, we use an existing React library like react-flow, once they support rendering compound/nested graph).

anthony-c-martin · 2021-04-26T14:39:08Z

You're definitely going to need to add a number of end-to-end tests for this functionality - including the client-side stuff like opening/closing panes etc.

anthony-c-martin · 2021-04-26T14:44:26Z

src/vscode-bicep/src/visualizer/app/components/Graph/style.ts

+const backgroundColor = "#333333";
+const backgroundColorSecondary = "#3f3f3f";
+const foregroundColor = "#ffffff";
+const foregroundColorSecondary = "#9c9c9c";
+const errorColor = "red";


Is there a way to inherit colors from the user theme rather than hard-coding them? Do we need to think about accessibility here?

Good question - technically we can read the colors from the user theme and send them to the webview, but there are concerns though:

A color theme usually contains numerous background and foreground color definitions for different UI areas. It will be hard to choose what colors to use.

We don't know what theme a user will use and if the graph will look good in that theme.

I'm leaning towards defining our own themes for the graph. This PR adds a dark theme, but later we can add a light theme and a high contrast theme (which addresses the accessibility issue).

Is there no standardization for how the colors are used? My assumption is that colors used for background vs foreground would have enough contrast to let people tell them apart.

Yes good call. There is Web Content Accessibility Guidelines (WCAG). Basically I think we'll want to meet the level AA success contrast criteria for the dark/light themes, and level AAA for the high contrast theme. There's an online tool to test that: https://webaim.org/resources/contrastchecker/.
I realized the foregroundColorSecondary is a bit too dark which does not pass the level AA test. I'll make some adjustment.

But even beyond that. VS code's own controls must be mapping these colors to themes somehow. Or rather each color "identifier" in VS code should have an intended usage (background, or various flavors of foreground colors). If we reuse those colors and match the intent of the particular color, wouldn't we get something that is theme-agnostic?

For example this tree view will always render ok no matter which theme you have (unless it's a really bad one):

I could be missing something here, though.

To create a VSCode theme you need to define colors for each UI controls individually, so it's basically a 1:1 mapping. I think the challenge is, because the colors are not designed for rendering a graph, it's pretty hard to map them to our graph components. For example, what color we should use as the canvas background? What color should we use as the graph node background? sideBar.background or panel.background? In some themes, those background colors are different (such as the built-in dark theme), while in other themes they can be the same (like the one I use):

I'm not against this approach as it avoids designing our own color scheme, and it provides a more consistent UX, but I doubt we can find a theme-agnostic mapping between theme colors and the graph components.

anthony-c-martin · 2021-04-26T14:45:55Z

src/vscode-bicep/src/visualizer/app/components/index.tsx

+
+const GlobalStyle = createGlobalStyle`
+  body {
+    font-family: Segoe UI, Helvetica Neue, Helvetica, sans-serif;


Are there any guidelines from VSCode about fonts? Any way to match this up with the theme?

AFAIK there's no guidelines for fonts to use in webviews. We can read --vscode-editor-font-family in a webview but that's the monospaced font for code. That being said, I found the following comment in VSCode's source code, and I think we can use the same fonts in our webview:

/** * The best font-family to be used in CSS based on the platform: * - Windows: Segoe preferred, fallback to sans-serif * - macOS: standard system font, fallback to sans-serif * - Linux: standard system font preferred, fallback to Ubuntu fonts * * Note: this currently does not adjust for different locales. */ export const DEFAULT_FONT_FAMILY = isWindows ? '"Segoe WPC", "Segoe UI", sans-serif' : isMacintosh ? '-apple-system, BlinkMacSystemFont, sans-serif' : 'system-ui, "Ubuntu", "Droid Sans", sans-serif';

If people ask, we can always expose as a setting.

Yeah good pt.

src/vscode-bicep/src/visualizer/view.ts

anthony-c-martin · 2021-04-26T14:47:32Z

src/vscode-bicep/src/visualizer/view.ts

+      <head>
+        <meta charset="UTF-8">
+        <!--
+        Use a content security policy to only allow loading images from https or from our extension directory,


Are you loading any external assets? If so, does this mean the functionality won't work without an internet connection?

No we are not loading any external assets. Adding a CSP will only block resources not comply with the policy, which should be orthogonal to internet connections.

anthony-c-martin · 2021-04-26T14:49:11Z

src/vscode-bicep/src/visualizer/view.ts

+  private static getNonce() {
+    let text = "";
+    const possible =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    for (let i = 0; i < 32; i++) {
+      text += possible.charAt(Math.floor(Math.random() * possible.length));
+    }
+    return text;
+  }


Unless there's some tangible security benefit from doing this (I'm assuming not since you're not using a crypto algorithm to generate the nonce), then would it be simpler to just hard-code the nonces for the two files?

Good point on using a crypto algorithm! This was copied from the vscode sample repo without me thinking too much...I would prefer not to use hard-coded nonces though, because it will pretty much defeat the entire purpose of using the nonce. Changed this to use crypto.randomBytes.

shenglol · 2021-04-27T06:45:14Z

You're definitely going to need to add a number of end-to-end tests for this functionality - including the client-side stuff like opening/closing panes etc.

Yeah, for sure. I've been trying to figure how to test webviews and I made some progress. I'll add end-to-end tests to this PR.

Update: added e2e tests.

shenglol · 2021-05-04T22:23:30Z

.github/workflows/build.yml

+
+      - name: Run snapshot tests
+        run: npm run test:snapshot
+        working-directory: ./src/vscode-bicep


I reorganized the build steps now that we get rid of tsc for unit tests and snapshot tests (they should happen before bundling).

majastrz · 2021-05-07T00:40:41Z

When you save an untitled file when the visualizer is active, is it possible to also rename the active visualizer tab? Right now it seems to be creating a new empty untitled file and leaving repointing the visualizer to that file, which clears the view.

majastrz

shenglol · 2021-05-07T02:06:02Z

When you save an untitled file when the visualizer is active, is it possible to also rename the active visualizer tab? Right now it seems to be creating a new empty untitled file and leaving repointing the visualizer to that file, which clears the view.

Good catch! It is possible, the built-in markdown preview extension does that, and I'll need to check their source code to see how that's implemented. As this PR is getting a bit overwhelming, I'll send separate PRs to implement the feature along with some other changes I want to make:

Add a light theme and high contrast theme and settings to choose a theme. By default it should match the current VSCode theme category (dark, light, or high contrast).
Update the fonts used in the webview to match what VSCode uses and (potentially) add settings that allow users to override them.
Double-clicking a resource/module node to reveal the corresponding declaration in the source code.
Add controls to refresh, zoom in, zoom out the graph, etc.

shenglol added 2 commits April 19, 2021 21:15

Add BicepDeploymentGraphHandler

33978ca

Implement Bicep visualizer

26739d9

shenglol mentioned this pull request Apr 22, 2021

We need a visualizer for Bicep #2358

Closed

shenglol commented Apr 22, 2021

View reviewed changes

src/vscode-bicep/package.json Outdated Show resolved Hide resolved

shenglol commented Apr 22, 2021

View reviewed changes

Merge branch 'main' into shenglol/bicep-visualizer

fb50323

Fix resourceLangId

9ac639d

majastrz reviewed Apr 22, 2021

View reviewed changes

src/Bicep.Core/Emit/ResourceDependencyVisitor.cs Outdated Show resolved Hide resolved

majastrz reviewed Apr 22, 2021

View reviewed changes

src/Bicep.LangServer/Handlers/BicepDeploymentGraphHandler.cs Show resolved Hide resolved

majastrz reviewed Apr 22, 2021

View reviewed changes

MarcusFelling mentioned this pull request Apr 22, 2021

Make ARM viewer a dependency microsoft/vscode-azurearmtools#444

Closed

shenglol added 3 commits April 25, 2021 17:17

Merge branch 'main' into shenglol/bicep-visualizer

08bcad8

Remove faultTolerant

e3b1e01

Fix build error

d67ef74

anthony-c-martin reviewed Apr 26, 2021

View reviewed changes

src/vscode-bicep/src/visualizer/view.ts Outdated Show resolved Hide resolved

anthony-c-martin reviewed Apr 26, 2021

View reviewed changes

shenglol added 6 commits April 30, 2021 10:57

Fix outputs of e2e tests

9b4cf3b

Fix copy path of bicep.tmLanguage

8ebb96d

E2E test now verifies bundled extension, use ts-jest for unit tests

d4b4e16

Merge branch 'main' into shenglol/bicep-visualizer

bf75c83

Run npm audit fix

df0b639

Add snapshot tests

b498716

shenglol added 4 commits April 30, 2021 23:14

Use crypto to generate nouce

d4b9c2f

Add e2e tests for visualizer

a861784

Fix snapshot tests

846ae9e

Refactor visualizer tests

4d183dd

shenglol commented May 4, 2021

View reviewed changes

shenglol added 2 commits May 4, 2021 20:51

Merge branch 'main' into shenglol/bicep-visualizer

62e54ea

Clean up comments

ec30a1e

majastrz approved these changes May 7, 2021

View reviewed changes

shenglol added 2 commits May 6, 2021 18:50

Update secondary foreground color

96542fb

Merge branch 'main' into shenglol/bicep-visualizer

e720375

shenglol enabled auto-merge (squash) May 7, 2021 02:08

shenglol merged commit 3acf968 into main May 7, 2021

shenglol deleted the shenglol/bicep-visualizer branch May 7, 2021 02:19

davidcorbin-atmosera mentioned this pull request Sep 30, 2021

NOT A BUG: How to Install (Bicep Visualizer) #4690

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bicep visualizer #2357

Bicep visualizer #2357

shenglol commented Apr 22, 2021 •

edited by alex-frankel

Loading

shenglol Apr 22, 2021 •

edited

Loading

shenglol Apr 22, 2021 •

edited

Loading

majastrz Apr 22, 2021

shenglol Apr 26, 2021 •

edited

Loading

majastrz May 6, 2021

MarcusFelling commented Apr 22, 2021

majastrz Apr 22, 2021

anthony-c-martin Apr 26, 2021

shenglol May 1, 2021

shenglol May 6, 2021

anthony-c-martin commented Apr 26, 2021

anthony-c-martin Apr 26, 2021

shenglol Apr 27, 2021

majastrz May 6, 2021

shenglol May 6, 2021

majastrz May 6, 2021

shenglol May 6, 2021 •

edited

Loading

anthony-c-martin Apr 26, 2021

shenglol Apr 27, 2021

majastrz May 6, 2021

shenglol May 7, 2021

anthony-c-martin Apr 26, 2021

shenglol Apr 27, 2021 •

edited

Loading

anthony-c-martin Apr 26, 2021

shenglol May 1, 2021

shenglol commented Apr 27, 2021 •

edited

Loading

shenglol May 4, 2021

majastrz commented May 7, 2021

majastrz left a comment

shenglol commented May 7, 2021 •

edited

Loading

Bicep visualizer #2357

Bicep visualizer #2357

Conversation

shenglol commented Apr 22, 2021 • edited by alex-frankel Loading

shenglol Apr 22, 2021 • edited Loading

Choose a reason for hiding this comment

shenglol Apr 22, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shenglol Apr 26, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MarcusFelling commented Apr 22, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anthony-c-martin commented Apr 26, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shenglol May 6, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shenglol Apr 27, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shenglol commented Apr 27, 2021 • edited Loading

Choose a reason for hiding this comment

majastrz commented May 7, 2021

majastrz left a comment

Choose a reason for hiding this comment

shenglol commented May 7, 2021 • edited Loading

shenglol commented Apr 22, 2021 •

edited by alex-frankel

Loading

shenglol Apr 22, 2021 •

edited

Loading

shenglol Apr 22, 2021 •

edited

Loading

shenglol Apr 26, 2021 •

edited

Loading

shenglol May 6, 2021 •

edited

Loading

shenglol Apr 27, 2021 •

edited

Loading

shenglol commented Apr 27, 2021 •

edited

Loading

shenglol commented May 7, 2021 •

edited

Loading