Add Breadcrumb export to Markdown

Author: v8vito

README.md

@@ -42,7 +42,7 @@ Security Notes allows the creation of notes within source files, which can be re
 
 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.
+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
 

package.json

@@ -104,6 +104,10 @@
       {
         "command": "security-notes.breadcrumbs.showTrailDiagram",
         "title": "Security Notes: Show Breadcrumb Diagram"
+      },
+      {
+        "command": "security-notes.breadcrumbs.exportTrail",
+        "title": "Security Notes: Export Breadcrumb Trail"
       }
     ],
     "configuration": {
@@ -272,6 +276,11 @@
           "command": "security-notes.breadcrumbs.createTrail",
           "group": "navigation@2",
           "when": "view == breadcrumbs-view"
+        },
+        {
+          "command": "security-notes.breadcrumbs.exportTrail",
+          "group": "navigation@3",
+          "when": "view == breadcrumbs-view"
         }
       ]
     },

src/breadcrumbs/commands.ts

@@ -5,6 +5,7 @@ import { BreadcrumbStore } from './store';
 import { Crumb, Trail } from '../models/breadcrumb';
 import { fullPathToRelative } from '../utils';
 import { formatRangeLabel, snippetPreview } from './format';
+import { exportTrailToMarkdown } from './export';
 
 interface TrailQuickPickItem extends vscode.QuickPickItem {
   trail: Trail;
@@ -104,6 +105,7 @@ export const revealCrumb = async (crumb: Crumb) => {
 
 interface RegisterBreadcrumbCommandsOptions {
   onShowTrailDiagram?: (trail: Trail) => Promise<void> | void;
+  onExportTrail?: (trail: Trail) => Promise<void> | void;
 }
 
 export const registerBreadcrumbCommands = (
@@ -264,5 +266,19 @@ export const registerBreadcrumbCommands = (
     }),
   );
 
+  disposables.push(
+    vscode.commands.registerCommand('security-notes.breadcrumbs.exportTrail', async () => {
+      const trail = await ensureActiveTrail(store);
+      if (!trail) {
+        return;
+      }
+      if (options.onExportTrail) {
+        await options.onExportTrail(trail);
+      } else {
+        await exportTrailToMarkdown(trail);
+      }
+    }),
+  );
+
   disposables.forEach((disposable) => context.subscriptions.push(disposable));
 };

src/breadcrumbs/export.ts

@@ -0,0 +1,112 @@
+'use strict';
+
+import * as vscode from 'vscode';
+import { Trail } from '../models/breadcrumb';
+import { formatRangeLabel } from './format';
+import { fullPathToRelative } from '../utils';
+
+const escapeCodeBlock = (value: string) => value.replace(/```/g, '\`\`\`');
+
+const headline = (level: number, text: string) => `${'#'.repeat(level)} ${text}`;
+
+const formatDate = (value: string | undefined) =>
+  value ? new Date(value).toLocaleString() : undefined;
+
+const buildSummary = (trail: Trail) => {
+  const files = new Set(trail.crumbs.map((crumb) => fullPathToRelative(crumb.uri.fsPath)));
+  const first = formatDate(trail.crumbs[0]?.createdAt);
+  const last = formatDate(trail.crumbs[trail.crumbs.length - 1]?.createdAt);
+
+  const lines: string[] = [];
+  lines.push(headline(2, 'Summary'));
+  lines.push('');
+  lines.push(`- **Total crumbs:** ${trail.crumbs.length}`);
+  lines.push(`- **Files touched:** ${files.size}`);
+  lines.push(`- **Generated:** ${formatDate(new Date().toISOString())}`);
+  if (first && last) {
+    lines.push(`- **Investigation window:** ${first} – ${last}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+};
+
+const buildCrumbSection = (trail: Trail) => {
+  const lines: string[] = [];
+  lines.push(headline(2, 'Trail'));
+  lines.push('');
+
+  trail.crumbs.forEach((crumb, index) => {
+    const filePath = fullPathToRelative(crumb.uri.fsPath);
+    const rangeLabel = formatRangeLabel(crumb.range);
+    const createdAt = formatDate(crumb.createdAt) ?? 'n/a';
+    lines.push(headline(3, `${index + 1}. ${filePath}:${rangeLabel}`));
+    lines.push('');
+    lines.push(`- **Captured:** ${createdAt}`);
+    if (crumb.note) {
+      lines.push(`- **Note:** ${crumb.note}`);
+    }
+    lines.push('');
+    lines.push('```');
+    lines.push(escapeCodeBlock(crumb.snippet));
+    lines.push('```');
+    lines.push('');
+  });
+
+  return lines.join('\n');
+};
+
+const generateTrailMarkdown = (trail: Trail) => {
+  const lines: string[] = [];
+  lines.push(headline(1, `Breadcrumb Trail – ${trail.name}`));
+  lines.push('');
+  if (trail.description) {
+    lines.push(trail.description);
+    lines.push('');
+  }
+  lines.push(buildSummary(trail));
+  lines.push(buildCrumbSection(trail));
+  return lines.join('\n');
+};
+
+export const exportTrailToMarkdown = async (trail: Trail, uri?: vscode.Uri) => {
+  if (!trail.crumbs.length) {
+    vscode.window.showInformationMessage('[Breadcrumbs] Cannot export an empty trail.');
+    return undefined;
+  }
+
+  const markdown = generateTrailMarkdown(trail);
+  const buffer = Buffer.from(markdown, 'utf8');
+
+  if (!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`,
+        )
+      : undefined;
+
+    uri = await vscode.window.showSaveDialog({
+      filters: { Markdown: ['md', 'markdown'] },
+      defaultUri,
+      saveLabel: 'Export Breadcrumb Trail',
+    });
+    if (!uri) {
+      return undefined;
+    }
+  }
+
+  await vscode.workspace.fs.writeFile(uri, buffer);
+
+  const selection = await vscode.window.showInformationMessage(
+    `Breadcrumb trail exported to ${uri.fsPath}.`,
+    'Open export',
+  );
+
+  if (selection === 'Open export') {
+    const document = await vscode.workspace.openTextDocument(uri);
+    await vscode.window.showTextDocument(document, { preview: false });
+  }
+
+  return uri;
+};

src/webviews/assets/breadcrumbs.js

@@ -7,6 +7,7 @@
   const content = document.getElementById('breadcrumbs-content');
   const createButton = document.querySelector('[data-action="create"]');
   const addButton = document.querySelector('[data-action="add"]');
+  const exportButton = document.querySelector('[data-action="export"]');
 
   let currentState;
 
@@ -40,6 +41,10 @@
     vscode.postMessage({ type: 'addCrumb' });
   });
 
+  exportButton.addEventListener('click', () => {
+    vscode.postMessage({ type: 'exportTrail' });
+  });
+
   function renderState(state) {
     populateTrailSelect(state);
 

src/webviews/breadcrumbs/breadcrumbsWebview.ts

@@ -6,6 +6,7 @@ import { Crumb, Trail } from '../../models/breadcrumb';
 import { formatRangeLabel, snippetPreview } from '../../breadcrumbs/format';
 import { fullPathToRelative } from '../../utils';
 import { revealCrumb } from '../../breadcrumbs/commands';
+import { exportTrailToMarkdown } from '../../breadcrumbs/export';
 
 interface WebviewCrumb {
   id: string;
@@ -42,7 +43,8 @@ type WebviewMessage =
   | { type: 'openCrumb'; trailId: string; crumbId: string }
   | { type: 'setActiveTrail'; trailId: string }
   | { type: 'createTrail' }
-  | { type: 'addCrumb' };
+  | { type: 'addCrumb' }
+  | { type: 'exportTrail' };
 
 export class BreadcrumbsWebview implements vscode.WebviewViewProvider, vscode.Disposable {
   public static readonly viewType = 'breadcrumbs-view';
@@ -114,9 +116,13 @@ export class BreadcrumbsWebview implements vscode.WebviewViewProvider, vscode.Di
           vscode.commands.executeCommand('security-notes.breadcrumbs.createTrail');
           break;
         }
-        case 'addCrumb': {
+        /*case 'addCrumb': {
           vscode.commands.executeCommand('security-notes.breadcrumbs.addCrumb');
           break;
+        }*/
+        case 'exportTrail': {
+          this.handleExportTrail();
+          break;
         }
         default: {
           break;
@@ -199,6 +205,17 @@ export class BreadcrumbsWebview implements vscode.WebviewViewProvider, vscode.Di
     revealCrumb(crumb);
   }
 
+  private async handleExportTrail() {
+    const activeTrail = this.store.getActiveTrail();
+    if (!activeTrail) {
+      vscode.window.showInformationMessage(
+        '[Breadcrumbs] Select a trail before exporting.',
+      );
+      return;
+    }
+    await exportTrailToMarkdown(activeTrail);
+  }
+
   private getHtmlForWebview(webview: vscode.Webview) {
     const scriptUri = webview.asWebviewUri(
       vscode.Uri.joinPath(
@@ -249,6 +266,7 @@ export class BreadcrumbsWebview implements vscode.WebviewViewProvider, vscode.Di
       <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>
       </div>
     </section>
     <section>