VScan v2.0 — Architectural Intelligence (VS Code Extension)

Local-first workspace mapping, dependency edges, blast radius, security scanning, SCA vulnerability detection, git churn analysis, and reachability analysis. All analysis runs on your machine — code never leaves your environment.

No separate server: the UI is a webview; npm run build:webview copies the React bundle into dist/webview, which is part of this extension. Packaged VSIX includes those files — users open any project; nothing is "ported" per workspace.

What's New in v2.0

🔒 SCA (Software Composition Analysis)

• Scans package.json, package-lock.json, go.mod, and requirements.txt
• Queries Google OSV (Open Source Vulnerabilities) database for known CVEs
• Local caching (24h TTL) in .vscan/sca-cache.json to minimize network calls
• Supports npm, Go, and Python ecosystems

🎯 Reachability Analysis (The "Star Feature")

• Automatically detects entry points (API routes, main files, Lambda handlers, etc.)
• Cross-references security + SCA findings with the dependency graph
• Tells you: "This SQLi is reachable from your public API" vs "This is in a test utility — lower priority"
• BFS traversal with depth tracking from entry points

🔥 Git Churn & Hotspot Detection

• File churn analysis (commit frequency in configurable time window)
• Code ownership tracking (who maintains each file)
• Hotspots: files that are both high-churn AND high-complexity — your top refactoring candidates

📊 Enhanced Health Score

• Now includes 8 factors: Dead Functions, Circular Deps, God Files, Coupling, Security, SCA Vulnerabilities, Hotspots, and Reachable Exposure
• More accurate grading that reflects real-world risk

📁 .vscan/ Directory

• All persistent data moved to .vscan/ (findings, config, SCA cache)
• Backward-compatible migration from legacy file locations
• Per-project config via .vscan/config.json

⚡ Incremental Scanning

• File watcher for on-save detection of changes
• Debounced incremental re-scan instead of full workspace rebuild

🩺 Remediation Engine (NEW)

• Deterministic, template-based security advice — no AI, no cloud, no data leaks
• Automatically detects your framework stack (React, Prisma, Express, Sequelize, etc.)
• Generates before/after code diffs for each vulnerability
• Context-aware: if DOMPurify is already installed, it suggests using it; if not, it suggests installing it
• Includes CWE IDs and OWASP Top 10 classifications for compliance tracking
• Suggests specific npm packages to install when applicable
• Links to official OWASP cheat sheets and library documentation

Development

1. Install dependencies

   npm install
   cd webview-ui && npm install && cd ..
   

2. Build (webview + TypeScript — one extension artifact)

   npm run build:all
   

   Or: npm run build:webview then npm run compile.

3. Run the extension (F5)

   • Simpler: open only the VScan repo folder → F5 → Run Extension.

   • To use VScan against a different repository without relying on a special dev workspace: run npm run build:all then vsce package, install the generated VSIX locally, and open any repo. The UI bundle is shipped inside the extension (no separate server).

If you see "VScan Webview build not found", run npm run build:webview from the repo root and reload the window.

Configuration

Create .vscan/config.json in your workspace root:

{
  "version": 2,
  "profiles": {
    "production": ["src/"],
    "frontend": ["apps/web/"],
    "scripts": ["scripts/"],
    "tests": ["__tests__/"]
  },
  "thresholds": {
    "blockerConfidence": 0.8,
    "godFileComplexity": 50,
    "godFileDependencies": 20,
    "highComplexityThreshold": 15,
    "churnDaysWindow": 90
  },
  "entryPoints": [
    "src/routes/api.ts",
    "src/index.ts"
  ]
}

Packaging

vscode:prepublish runs build:webview then compile, so packaged VSIX includes the React UI.

npm run build:all
vsce package

Commands

• VScan: Open Architecture Map
• VScan: Analyze Blast Radius (context menu / command palette)

Architecture (src/)

See docs/PRD_IMPLEMENTATION_PLAN.md for the product roadmap.