feat(vscode-extension): improve UX/DX, add minSeverity config, and harden extension API stability

[codemagician1949]

Summary

This PR addresses the UX/DX gap in the vscode-extension component, with particular focus on extension API stability (issue #621). The changes make the extension more predictable for users, composable for downstream extensions, and better aligned with VS Code best practices.

---

Changes

sanctifier.minSeverity configuration (UX)

A new setting lets users control which severity levels are surfaced as editor diagnostics:

"sanctifier.minSeverity": "warning"   // "error" | "warning" | "information"

Default is "warning" — informational hints are suppressed unless explicitly opted in. The analyzeWorkspace CLI command also forwards --min-severity so the output channel and the in-editor view stay consistent.

Stable public extension API

activate() now returns a typed SanctifierExtensionApi object that other extensions can consume:

const api = vscode.extensions
  .getExtension<SanctifierExtensionApi>('sanctifier.sanctifier-soroban')
  ?.exports;

api?.getFindings(document.uri.toString()); // EditorFinding[]
api?.version;                              // "0.1.0"

The interface is exported from src/types.ts and versioned with the package.

Output channel (DX)

analyzeWorkspace no longer opens an untitled JSON document. Instead it streams to a persistent "Sanctifier" output channel that:

• Stays open between runs
• Shows stderr and exit-code context
• Can be revealed with the new Sanctifier: Show output channel command

Status bar + toggle command

• A status bar item (left side) shows the live finding count or Sanctifier: off
• Clicking it — or running Sanctifier: Toggle enable/disable — flips sanctifier.enable globally without opening settings

Content-change cache

runAnalysis now skips re-parsing when the document text has not changed since the last run, reducing unnecessary work during cursor-only movements that trigger onDidChangeTextDocument.

onDidChangeWorkspaceFolders handler

When workspace folders are added/removed the workspace detection cache is invalidated and all open documents are rescheduled.

New filterBySeverity / SEVERITY_ORDER utilities (analyzer.ts)

export const SEVERITY_ORDER: Record<Severity, number> = { information: 0, warning: 1, error: 2 };
export function filterBySeverity(findings: EditorFinding[], minSeverity: Severity): EditorFinding[];

These are pure functions that make severity filtering testable in isolation without a VS Code host.

Test suite extended (19 tests total, all passing)

Seven new tests cover filterBySeverity and SEVERITY_ORDER:

• ranks information < warning < error
• passes all findings when minSeverity is information
• drops information-level findings when minSeverity is warning
• keeps only errors when minSeverity is error
• returns empty array when no findings meet threshold
• returns empty array for empty input

---

CI

• npm run lint (tsc --noEmit) — clean
• npm test (compile + node --test) — 19/19 pass
• npx @vscode/vsce package — packages without warnings

---

Documentation

VS Code extension API surface documented in DOCUMENTATION_INDEX.md under VS Code Extension.

---

Closes #621
Closes #607
Closes #625
Closes #629

[vercel]

@Gbangbolaoluwagbemiga is attempting to deploy a commit to the gbangbolaoluwagbemiga's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@codemagician1949 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits