⚡ Highlights at a Glance
| Module |
What It Solves |
Key Superpower |
| 1. Architecture Visualizer |
Invisible prop-drilling & hidden re-renders |
Interactive React Flow AST with Dagre auto-layout & blast radius analysis |
| 2. Dead Code Reaper |
Fear of deleting orphaned code |
BFS reachability scan from entry points + safe .trash/ archiving with 1-click restore |
| 3. Codebase Tours |
Fragmented PR reviews & onboarding friction |
Git-versioned .tour.json steps with fuzzy snippet anchor recovery & inline comments |
🔬 Interactive Component Visualizer
Right-click any .tsx or .jsx component and select "ArchLens: Visualize Component Architecture". ArchLens parses your TypeScript AST, traces prop flows upstream, and renders an animated hierarchical dependency canvas:
flowchart TD
subgraph S1["Upstream Prop-Drilling Trace"]
App["App (Origin: userRole state)"] -->|"userRole (hop 1)"| DL["DashboardLayout"]
DL -->|"userRole (hop 2)"| SB["Sidebar"]
SB -->|"⚠️ userRole (depth 3 - threshold exceeded)"| UN["UserNav"]
UN -->|"⚠️ userRole (depth 4)"| UP["UserProfileBadge (Leaf Consumer & ThemeContext)"]
end
subgraph S2["Re-render Blast Radius Analysis"]
App -.->|"⚡ Guaranteed Re-render"| LC["LiveCounter (Un-memoized)"]
App -.->|"🛡️ Prevented by memo"| MA["MemoizedAnalyticsWidget (React.memo)"]
end
classDef origin fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#38bdf8;
classDef warning fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fbbf24;
classDef leaf fill:#0f172a,stroke:#c084fc,stroke-width:2px,color:#c084fc;
classDef unmemo fill:#1e293b,stroke:#ef4444,stroke-width:1.5px,color:#fca5a5;
classDef memo fill:#1e293b,stroke:#22c55e,stroke-width:1.5px,color:#86efac;
class App origin;
class SB,UN warning;
class UP leaf;
class LC unmemo;
class MA memo;
What ArchLens Detects in Real-Time:
- 🔗 Deep Prop-Drilling Chains: Flags any prop passed through more than 2 hops (
⚠️ Prop-drilling threshold exceeded).
- ⚡ Re-Render Blast Radius: Flags child components that are guaranteed to re-render upon parent state updates versus those shielded with
React.memo (prevented_by_memo).
- 🌐 Context & Hook Metrics: Detects
useContext(...) consumers and highlights .Provider origins.
- 🎯 Click-to-Jump: Clicking any node in the React Flow canvas immediately jumps your VS Code cursor to that component's file and line declaration.
- 🚀 Auto-Generate Tour: Click "Auto-Generate Tour" directly in the visualizer to turn any deep prop-drilling chain into a step-by-step walkthrough.
🛡️ Safe Reaper & Tour Protection
Deleting dead code shouldn't be risky. ArchLens scans your workspace from configured entry points (src/index.*, app/**/page.*, pages/**/*, package.json scripts) while honoring .gitignore and .archlensignore:
flowchart LR
Scan["Workspace Reachability Scan"] -->|"Detect Unreachable"| Orphans["📁 Orphan Files & Unused CSS"]
Orphans --> Check{"Referenced in .tour.json?"}
Check -->|"Yes ⚠️"| Warning["Tour Reference Warning Modal Intercepts"]
Check -->|"No"| Archive["Safe Archive to .trash/<timestamp>/"]
Warning -->|"User Confirms"| Archive
Archive --> Manifest["restore-manifest.json Created"]
Manifest -->|"1-Click Action"| Restore["Full Original Location Restore"]
classDef danger fill:#1e293b,stroke:#ef4444,stroke-width:1.5px,color:#f87171;
classDef safe fill:#0f172a,stroke:#22c55e,stroke-width:1.5px,color:#86efac;
classDef warn fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fbbf24;
class Orphans danger;
class Warning warn;
class Archive,Manifest,Restore safe;
Reaper Superpowers:
- 📁 Grouped Categorization:
- Unreachable Orphan Files: Complete with file size badges.
- Unused Exports: Exported symbols never imported across the workspace.
- Unreferenced CSS / Styles: Unused stylesheets.
- Unused
package.json Dependencies: Dependencies never imported in source files or scripts.
- 🛡️ Tour Reference Safety Barrier: If an orphaned file is referenced by an active tour (
.tours/*.tour.json), ArchLens intercepts the archiving action with an interactive confirmation warning.
- 📦 Safe
.trash/ Archiving: Files are isolated to timestamped .trash/<timestamp>/ folders along with a restore-manifest.json.
- ⏪ One-Click Restore: Restores all archived files back to their exact original workspace locations at any time.
🚀 Codebase Tours & Walkthroughs
Create, version-control, and replay step-by-step architectural guides stored directly in .tours/*.tour.json:
- Record Mode: Highlight any lines in your editor -> right-click "ArchLens: Add Tour Step at Cursor".
- Playback Mode: Step through walkthroughs using
Alt + Right and Alt + Left with highlighted editor ranges (TextEditorDecorationType) and inline Markdown cards powered by vscode.comments.createCommentController.
- Fuzzy Line-Anchor Recovery: When code edits shift line positions, ArchLens searches surrounding anchor snippets to automatically relocate and highlight the intended code block.
⌨️ Keyboard Shortcuts
| Shortcut |
Command |
When |
| Alt + → |
archlens.tours.nextStep |
Active tour playback |
| Alt + ← |
archlens.tours.prevStep |
Active tour playback |
| Esc |
archlens.tours.endTour |
Active tour playback |
Right-Click .tsx |
archlens.visualizeComponent |
Inside React / Next.js file |
| Right-Click Selection |
archlens.tours.recordStep |
Any text editor focus |
⚙️ Extension Settings
Configure ArchLens via VS Code settings.json:
{
// Entry points used to determine workspace reachability
"archlens.reaper.entryPoints": [
"src/index.{ts,tsx,js,jsx}",
"src/main.{ts,tsx,js,jsx}",
"src/App.{ts,tsx,js,jsx}",
"app/**/page.{ts,tsx,js,jsx}",
"app/**/layout.{ts,tsx,js,jsx}",
"pages/**/*.{ts,tsx,js,jsx}"
],
// Patterns to exclude from dead code scanning
"archlens.reaper.ignorePatterns": [
"**/*.d.ts",
"**/*.test.{ts,tsx,js,jsx}",
"**/*.spec.{ts,tsx,js,jsx}",
"**/__tests__/**",
"**/node_modules/**",
"**/.next/**",
"**/dist/**",
"**/.trash/**"
],
// Prop drilling depth threshold for warning highlights
"archlens.visualizer.maxPropDrillingDepth": 2
}
🧪 Live Test Repository
A complete, pre-configured sandbox repository is ready to test all 3 modules:
👉 archlens-test-repo
- Exercises 4-level deep prop drilling chains.
- Demonstrates un-memoized vs.
React.memo shielded blast radius.
- Includes pre-configured orphan files, unreferenced CSS, and tour protection tests.
📦 Building from Source
# 1. Clone repository
git clone https://github.com/archlens/archlens-vscode.git
cd archlens-vscode
# 2. Install dependencies
npm install
npm --prefix webview-ui install
# 3. Build Webview & Extension Host
npm run build
# 4. Package into .vsix release
npm run package
Built with ❤️ by the ArchLens Architecture Team • Distributed under the MIT License