vscode

Instruction file imported from zotoio/x-fidelity (.cursor/rules/vscode.mdc). Copyright stays with the author.

Improving X-Fidelity VS Code Extension: Performance, Reliability, and UX Optimizing Extension Performance and Stability (All Platforms) Lazy Activation: Ensure the extension activates only when needed. Define specific activationEvents (e.g. on particular commands or file types) instead of activating on every startup. VS Code’s design encourages lazy-loading extensions so they don’t slow down editor startup or UI responsiveness code.visualstudio.com . For example, if X-Fidelity analyzes code files, activate on those file open events rather than "*" on startup. This prevents unnecessary CPU/memory use when the extension isn’t in use code.visualstudio.com . Non-Blocking Operations: Audit long-running tasks (like code analysis in XFI). Run them asynchronously and off the UI thread. If the extension performs heavy analysis on files, use Promise/async APIs or the Language Server pattern so computations run in a separate process. VS Code extensions should avoid blocking the event loop, as misbehaving extensions are prevented from slowing down the UI code.visualstudio.com . Consider using a Language Server (if applicable) or Node worker threads for CPU-intensive work, keeping the UI thread free. Efficient Scanning & Caching: Since XFI likely scans project files, implement caching (the monorepo has a cacheManager.ts). Only re-scan files that changed, and cache results to avoid repetitive work. Use VS Code’s file system APIs or workspace.onDidSaveTextDocument events to trigger incremental analysis. This will improve runtime performance especially on large projects. Reduce Logging Overhead: The extension has logging utilities. Ensure that debug logs or telemetry (e.g., telemetryRoute) are disabled or minimized in production runtime. Excessive logging can slow down an extension. Provide an option to turn on verbose logging for troubleshooting, but keep the default lean. Memory Management: Clean up resources to improve reliability over long sessions. For example, dispose of event listeners, diagnostics, or timers when no longer needed. Use VS Code’s Disposable pattern to tie cleanup to extension deactivation or workspace closure. This prevents memory leaks and keeps the extension stable on Linux/Mac where users might keep sessions running longer. Strengthening Testing and Reliability Use Standard VS Code Test Tools (Mocha): Adopt VS Code’s official testing framework for extensions. The VS Code team provides a test CLI (@vscode/test-cli) which uses Mocha under the hood for integration tests code.visualstudio.com . Ensure your monorepo’s test setup (likely already including Mocha via the scaffolded files) is configured with this. You can run yarn test to execute integration tests in a headless VS Code instance code.visualstudio.com . Using the standard framework improves reliability and makes tests easier to run and debug (for example, via the “Extension Tests” launch config or the Test Runner extension). Integration Tests in the Extension Host: Write integration tests that simulate real usage of the extension within VS Code. The scaffold (e.g. src/test/suite) already has examples. These tests run in the Extension Development Host and can use the full VS Code API code.visualstudio.com , allowing you to verify that commands, tree views, and diagnostics behave as expected. For instance, you might open a workspace with known issues and assert that X-Fidelity’s issues tree or diagnostics appear with the correct line/column. Unit Tests for Core Logic: In addition to integration tests, ensure pure logic (especially in x-fidelity-types and any analytic functions) has fast unit tests. Use Mocha (or Jest if preferred for unit tests) to run these without needing the VS Code runtime. This will catch logic bugs quickly. The monorepo’s structure suggests x-fidelity-types contains core logic (and indeed has its own core.test.ts); keep those tests running as part of the build. Cross-Platform CI: Set up Continuous Integration to run tests on Linux and macOS (and optionally Windows) to cover all supported platforms. VS Code’s documentation notes that Azure Pipelines or GitHub Actions can run extension tests on Windows, macOS, and Linux images code.visualstudio.com . This is important because file paths, case-sensitivity, or other OS-specific nuances could affect your extension. For example, use a matrix in your CI config to run yarn compile && yarn test on Ubuntu and macOS. Catching test failures on these platforms will improve reliability for all users. Mocha Config and Timeouts: When using Mocha for integration tests, ensure the timeout is generous (VS Code startup + extension activation can take a couple of seconds). The VS Code test sample sets a timeout around 20 seconds for integration tests code.visualstudio.com . You can adjust Mocha options (e.g., in .vscode-test.js or the runTests call) to avoid flaky tests. Also use Mocha’s hooks (before, after) to set up or clean state (e.g., open a test workspace or reset any singleton state in the extension between tests). Error Handling in Tests: Write tests for failure scenarios as well. For instance, if the XFI server (if any) is unreachable or a parsing error occurs, the extension should handle it gracefully (perhaps show a notification instead of throwing). Create tests that simulate these conditions (you might mock the server module or force an exception in analysis) to ensure the extension doesn’t crash the extension host. This improves reliability at runtime – the extension will be more robust against unexpected inputs. Simplifying the User Interface and Experience Trim Unnecessary UI Features: Review all contributed UI elements (panels, tree views, status bar items, etc.) and remove anything not essential. The goal is a clean, intuitive UX that focuses on showing code issues. According to VS Code’s UX guidelines, extensions should avoid contributing too many custom views or duplicating existing functionality code.visualstudio.com code.visualstudio.com . For example, if X-Fidelity currently adds multiple side bar panels (Dashboard, Control Center, Settings UI, etc.), consider consolidating these into one view container or using native VS Code UI where possible. A single “X-Fidelity” activity bar icon with a tree view for issues is likely sufficient (3-5 views in one container is a comfortable max code.visualstudio.com ). Avoid multiple separate panels that could confuse or clutter the interface. Leverage VS Code Native UI: Prefer native constructs like the Problems panel, Quick Pick, and Status Bar over custom webviews for basic interactions. The monorepo’s issueDetailsPanel.ts and other panels suggest a custom webview is used to display issue details. Ask if this is truly necessary. Often, a simpler route is to use the Problems panel (via diagnostics) for error lists and let users click to navigate (more on that below), and use hover tooltips or Markdown in a QuickPick/notification for any additional info. VS Code’s guidelines explicitly suggest limiting custom Webview usage unless absolutely needed code.visualstudio.com . Removing heavy webviews (like a complex dashboard) will not only simplify UX but also improve performance (Webviews can be memory- and CPU-heavy). If a configuration wizard exists as a webview, consider replacing it with standard input prompts or commands (for example, using the vscode.window.showInputBox or Quick Pick for configuration steps). This streamlining makes the extension feel more integrated with VS Code itself. Streamlined Commands: Audit commands and context menu items exposed by the extension. Remove any that are redundant or not crucial. Every command in the palette or right-click menu should serve a clear purpose. If some commands were only for debugging or rarely used features, consider removing or hiding them to reduce user confusion. Also, use clear naming for commands so users understand their function (the monorepo’s README/Development docs can help decide which features are truly needed). A simpler feature set focusing on the core value (surfacing code issues) will enhance user trust and ease of use. Focusing on Precise Issue Location Display (XFI_RESULT) One of the highest-impact improvements is to clearly show each issue’s exact file, line, and column to the user, so they can jump right to the problem in code. Here’s a roadmap for achieving this in a user-friendly way: Use Diagnostics for Issues: Leverage VS Code’s Diagnostics API to represent XFI issues. Each issue from the XFI_RESULT object (presumably containing file path, line, col, message, etc.) can be turned into a vscode.Diagnostic and added to a DiagnosticCollection. VS Code will then automatically list these in the Problems panel, with file names, line/column, and message stackoverflow.com . This is the simplest way to display precise locations – the Problems panel is a familiar UI for developers and supports click-to-navigate. (If your extension currently only shows issues in a custom tree or panel, adding Diagnostics will integrate it with VS Code’s standard error display.) According to VS Code’s docs, using vscode.Diagnostic entries is how extensions surface errors or lint findings in the editor stackoverflow.com . Auto-Navigation on Click: Ensure that when an issue is selected (whether from your tree view or the Problems panel), the editor opens the corresponding file and reveals the exact position. If you use Diagnostics as above, VS Code handles the click navigation in the Problems panel automatically. If you keep a custom Issues Tree View, implement a TreeItem.command that calls vscode.window.showTextDocument(uri, { selection: range }) – so selecting an item opens the file at the issue’s range. The key is that the user should be able to go from the list of issues to the code with one action. This addresses the core usability goal: no hunting for the line manually. Show Line/Col in UI Labels: It’s helpful to display the line/column numbers in the issue list UI as well. For example, in the Tree View’s label or description for each issue item, append “(line X, col Y)” to give users context at a glance. This is especially useful if the extension groups issues (e.g., under file nodes). Keeping that information visible reinforces that the extension is precise and points exactly to the problem. Inline Code Highlights (Optional): For an even better experience, consider adding subtle inline decorations to highlight the affected code range. For example, use vscode.window.createTextEditorDecorationType to underline or gutter-mark the exact code at fault. This, combined with jumping to the location, makes it very clear what the issue is. However, use this sparingly and only when the editor for that file is visible, to avoid performance costs. Remove Redundant Issue Views: If the extension previously opened a separate “Issue Details” webview/panel showing the issue and location, you might retire that in favor of the above approach. The VS Code editor itself can display the context (the code around the issue) and the Problems panel/tree shows the description. This reduces UI duplication. The guideline “don’t repeat existing functionality” applies here – since VS Code already can list and navigate to errors, we utilize that rather than a custom details panel code.visualstudio.com . If extra details (like an explanation or recommended fix) are part of XFI_RESULT, these can be included in the Diagnostic’s message or as an hover (you can use Markdown in diagnostic messages for richer info). Another approach is to implement a Code Action or Quick Fix if applicable, so the user sees a lightbulb and can perform a fix or see more info. The codebase has a codeActionProvider.ts, suggesting this may already be in progress. By focusing on the above changes – optimizing performance, using standard testing practices, simplifying the UX, and surfacing issue locations clearly – the X-Fidelity extension will become faster, more reliable, and much more user-friendly. These steps follow VS Code’s best-practice recommendations and examples, emphasizing minimal disruption to the user’s workflow and leveraging the power of VS Code’s native features (Problems panel, diagnostics, etc.) to provide a seamless experience code.visualstudio.com code.visualstudio.com stackoverflow.com . All unnecessary complexity (both in UI and internal logic) can be trimmed, allowing the extension to do its primary job extremely well: help the user pinpoint and resolve issues in their code with high precision and confidence. Sources: Visual Studio Code Extension Host – Stability and Performance code.visualstudio.com VS Code UX Guidelines – Sidebars and Views (avoid clutter and duplicate UI) code.visualstudio.com code.visualstudio.com VS Code Extension API – using Diagnostics for Problems panel integration stackoverflow.com VS Code Testing Guide – Running Extension Tests with Mocha code.visualstudio.com VS Code Continuous Integration – Testing on Windows, macOS, and Linux code.visualstudio.com VS Code Extension Capabilities – Using diagnostics to report errors code.visualstudio.com