Fix Breadcrumbs webview and update README

Author: v8vito

README.md

@@ -38,35 +38,19 @@ Security Notes allows the creation of notes within source files, which can be re
 
 ![Demo for basic usage](images/demo-basic-usage.gif)
 
-## Breadcrumb Trails
-
-Breadcrumbs let you capture the path you follow while reverse-engineering a feature. Start a trail with `Security Notes: Create Breadcrumb Trail`, highlight the snippets you visit, and run `Security Notes: Add Breadcrumb Crumb` to drop "crumbs" along the way. Each crumb stores the code selection, file/line information, and an optional note.
-
-Open the **Breadcrumbs** view from the Security Notes activity bar to see an interactive diagram of the active trail. Click any crumb in the diagram to jump back to that snippet in the editor, or switch trails from the dropdown to review other investigations. Trails are stored locally in `.security-notes-breadcrumbs.json` so you can revisit them later, and you can export the active trail to a Markdown report (via `Security Notes: Export Breadcrumb Trail` or the Export button) ready to paste into docs or reports.
-
 ## Local database for Comments
 
 By default your notes are backed up in a JSON file once you close VSCode. Once you open the project again, saved comments are loaded and shown on the UI.
 
-## Collaboration Mode
-
-Because chasing bugs with friends is more fun :)
-
-Security Notes allows sharing of notes in real-time with other users. To do so, it leverages the RethinkDB real-time database.
-
-First, make sure you have a RethinkDB database instance up and running. Then set your author name, and the database connection information in the extension's settings, and you are ready to go! Please see the section below for more details).
-
-Collaboration mode in action:
-
-![Demo for collaboration](images/demo-collaboration.gif)
+## Breadcrumb Trails
 
-### Setting up the RethinkDB database
+Breadcrumbs let you capture the path you follow while reverse-engineering a feature. Start a trail with `Security Notes: Create Breadcrumb Trail`, highlight the snippets you visit, and run `Security Notes: Add Breadcrumb to Trail` to drop "crumbs" along the way. Each crumb stores the code selection, file/line information, and an optional note.
 
-We recommend following instructions in RethinkDB [installation guide](https://rethinkdb.com/docs/install/). Additionally, following [hardening steps](https://rethinkdb.com/docs/security/#wrapper), such as setting a password for the `admin` user and setting up SSL/TLS, are strongly encouraged.
+![Breadcrumbs view showing a trail](images/breadcrumbs-1.png)
 
-Naturally, you will want to collaborate with remote peers. To do so in a secure way, we recommend setting up access to RethinkDB via SSH or through a VPN like [Tailscale](http://tailscale.com). This way, you avoid having to expose the instance to any network, and also ensuring information in transit is encrypted.
+Open the **Breadcrumbs** view from the Security Notes activity bar to see an interactive diagram of the active trail. Click any crumb in the diagram to jump back to that snippet in the editor, or switch trails from the dropdown to review other investigations. Trails are stored locally in `.security-notes-breadcrumbs.json` so you can revisit them later, and you can export the active trail to a Markdown report (via `Security Notes: Export Breadcrumb Trail` or the Export button) ready to paste into docs or reports.
 
-> **Important Notices:** When collaborating with others, ensure that all VSCode instances open the project from the same relative location. For example, if the source code repository you're reviewing has a directory structure like `source_code/app/src`, all peers should open VScode at the same level. Security Notes will store note location using relative paths, so they should be consistent. Also, after enabling the collaboration setting, VSCode would need to be restarted/reloaded for the change to have effect.
+![Markdown export of a Breadcrumb](images/breadcrumbs-2.png)
 
 ## Importing SAST results
 
@@ -97,6 +81,26 @@ gosec -fmt=json -out=gosec-results.json ./...
 semgrep scan --json -o semgrep-results.json --config=auto .
 ```
 
+## Collaboration Mode
+
+Because chasing bugs with friends is more fun :)
+
+Security Notes allows sharing of notes in real-time with other users. To do so, it leverages the RethinkDB real-time database.
+
+First, make sure you have a RethinkDB database instance up and running. Then set your author name, and the database connection information in the extension's settings, and you are ready to go! Please see the section below for more details).
+
+Collaboration mode in action:
+
+![Demo for collaboration](images/demo-collaboration.gif)
+
+### Setting up the RethinkDB database
+
+We recommend following instructions in RethinkDB [installation guide](https://rethinkdb.com/docs/install/). Additionally, following [hardening steps](https://rethinkdb.com/docs/security/#wrapper), such as setting a password for the `admin` user and setting up SSL/TLS, are strongly encouraged.
+
+Naturally, you will want to collaborate with remote peers. To do so in a secure way, we recommend setting up access to RethinkDB via SSH or through a VPN like [Tailscale](http://tailscale.com). This way, you avoid having to expose the instance to any network, and also ensuring information in transit is encrypted.
+
+> **Important Notices:** When collaborating with others, ensure that all VSCode instances open the project from the same relative location. For example, if the source code repository you're reviewing has a directory structure like `source_code/app/src`, all peers should open VScode at the same level. Security Notes will store note location using relative paths, so they should be consistent. Also, after enabling the collaboration setting, VSCode would need to be restarted/reloaded for the change to have effect.
+
 ## Exporting notes in popular formats
 
 Currently we only support exporting notes to Markdown, but other formats such as HTML are coming soon.

images/breadcrumbs-1.png

@@ -91,15 +91,15 @@
       },
       {
         "command": "security-notes.breadcrumbs.addCrumb",
-        "title": "Security Notes: Add Breadcrumb Crumb"
+        "title": "Security Notes: Add Breadcrumb to Trail"
       },
       {
         "command": "security-notes.breadcrumbs.removeCrumb",
         "title": "Security Notes: Remove Breadcrumb Crumb"
       },
       {
         "command": "security-notes.breadcrumbs.editCrumbNote",
-        "title": "Security Notes: Edit Breadcrumb Crumb Note"
+        "title": "Security Notes: Edit Breadcrumb Note"
       },
       {
         "command": "security-notes.breadcrumbs.showTrailDiagram",
@@ -320,4 +320,4 @@
     "rethinkdb": "^2.4.2",
     "uuid": "^9.0.0"
   }
-}
+}

images/breadcrumbs-2.png

@@ -7,6 +7,8 @@ import { fullPathToRelative } from '../utils';
 import { formatRangeLabel, snippetPreview } from './format';
 import { exportTrailToMarkdown } from './export';
 
+let lastActiveEditor: vscode.TextEditor | undefined = vscode.window.activeTextEditor ?? undefined;
+
 interface TrailQuickPickItem extends vscode.QuickPickItem {
   trail: Trail;
 }
@@ -115,6 +117,14 @@ export const registerBreadcrumbCommands = (
 ) => {
   const disposables: vscode.Disposable[] = [];
 
+  disposables.push(
+    vscode.window.onDidChangeActiveTextEditor((editor) => {
+      if (editor) {
+        lastActiveEditor = editor;
+      }
+    }),
+  );
+
   disposables.push(
     vscode.commands.registerCommand('security-notes.breadcrumbs.createTrail', async () => {
       const name = await vscode.window.showInputBox({
@@ -156,14 +166,16 @@ export const registerBreadcrumbCommands = (
 
   disposables.push(
     vscode.commands.registerCommand('security-notes.breadcrumbs.addCrumb', async () => {
-      const editor = vscode.window.activeTextEditor;
+      const editor = vscode.window.activeTextEditor ?? lastActiveEditor;
       if (!editor) {
         vscode.window.showInformationMessage(
           '[Breadcrumbs] Open a file and select the code you want to add as a crumb.',
         );
         return;
       }
 
+      await vscode.commands.executeCommand('workbench.action.focusActiveEditorGroup');
+
       const trail = await ensureActiveTrail(store);
       if (!trail) {
         return;

package.json

@@ -21,11 +21,8 @@ const buildSummary = (trail: Trail) => {
   lines.push(headline(2, 'Summary'));
   lines.push('');
   lines.push(`- **Total crumbs:** ${trail.crumbs.length}`);
-  lines.push(`- **Files touched:** ${files.size}`);
+  lines.push(`- **Source Files Involved:** ${files.size}`);
   lines.push(`- **Generated:** ${formatDate(new Date().toISOString())}`);
-  if (first && last) {
-    lines.push(`- **Investigation window:** ${first} – ${last}`);
-  }
   lines.push('');
   return lines.join('\n');
 };
@@ -81,9 +78,9 @@ export const exportTrailToMarkdown = async (trail: Trail, uri?: vscode.Uri) => {
     const fileNameSafe = trail.name.replace(/[^a-z0-9\-_]+/gi, '-').replace(/-+/g, '-');
     const defaultUri = vscode.workspace.workspaceFolders?.length
       ? vscode.Uri.joinPath(
-          vscode.workspace.workspaceFolders[0].uri,
-          `${fileNameSafe || 'breadcrumb-trail'}.md`,
-        )
+        vscode.workspace.workspaceFolders[0].uri,
+        `${fileNameSafe || 'breadcrumb-trail'}-Breadcrumb.md`,
+      )
       : undefined;
 
     uri = await vscode.window.showSaveDialog({

src/breadcrumbs/commands.ts

@@ -12,7 +12,7 @@
 }
 
 .breadcrumbs-subtitle {
-  margin: 0.25rem 0 0;
+  margin: 0.10rem 0 0;
   color: var(--vscode-descriptionForeground);
   font-size: 0.85rem;
 }
@@ -29,6 +29,7 @@
   border-radius: 4px;
   padding: 0.3rem 0.8rem;
   cursor: pointer;
+  white-space: nowrap;
 }
 
 .breadcrumbs-button:hover {
@@ -114,10 +115,11 @@
   font-size: 0.75rem;
   letter-spacing: 0.06em;
   text-transform: uppercase;
-  background: var(--vscode-textLink-activeForeground, rgba(100, 149, 237, 0.25));
-  color: var(--vscode-textLink-foreground);
-  border-radius: 999px;
-  padding: 0.1rem 0.6rem;
+  background: var(--vscode-editorWidget-background);
+  border: 1px solid var(--vscode-editorWidget-border);
+  color: var(--vscode-editor-foreground);
+  border-radius: 5px;
+  padding: 0.15rem 0.5rem;
   font-weight: 600;
 }
 
@@ -182,4 +184,4 @@
 .crumb-snippet:hover {
   border-color: var(--vscode-focusBorder);
   box-shadow: 0 0 0 1px var(--vscode-focusBorder);
-}
+}

src/breadcrumbs/export.ts

@@ -37,9 +37,9 @@
     vscode.postMessage({ type: 'createTrail' });
   });
 
-  addButton.addEventListener('click', () => {
-    vscode.postMessage({ type: 'addCrumb' });
-  });
+  if (addButton) {
+    addButton.remove();
+  }
 
   exportButton.addEventListener('click', () => {
     vscode.postMessage({ type: 'exportTrail' });

src/webviews/assets/breadcrumbs.css

@@ -259,14 +259,15 @@ export class BreadcrumbsWebview implements vscode.WebviewViewProvider, vscode.Di
   </head>
   <body>
     <section class="breadcrumbs-header">
-      <div>
-        <h2 class="breadcrumbs-title">Breadcrumb trails</h2>
-        <p class="breadcrumbs-subtitle">Visualise how you navigated complex features.</p>
+    <!--  
+    <div>
+        <h2 class="breadcrumbs-title">Breadcrumbs</h2>
+        <p class="breadcrumbs-subtitle">Use this feature to track complex implementations throughout different source code files. Start by creating a Trail, and then add crumbs to code snippets as you dig deeper into an implementation.</p>
       </div>
+      -->
       <div class="breadcrumbs-actions">
-        <button class="breadcrumbs-button" data-action="create">New trail</button>
-        <button class="breadcrumbs-button" data-action="add">Add crumb</button>
-        <button class="breadcrumbs-button" data-action="export">Export</button>
+        <button class="breadcrumbs-button" data-action="create">New Trail</button>
+        <button class="breadcrumbs-button" data-action="export">Export Trail</button>
       </div>
     </section>
     <section>