🔍 VS Config Extension - Complete User Guide

A VS Code extension for enhanced navigation and reference finding in JSON/JSON5 configuration files, designed for templated report systems with intelligent caching and organized results.

🚀 Quick Start

Basic Usage:

1. Open any .json or .json5 file in your CSV directory
2. Position cursor over any template name
3. Right-click → "Find References in Explorer"
4. View results in the References Explorer panel (📚 in Activity Bar)

Panel Access:

• Activity Bar: Click the References Explorer icon (📚)
• Command Palette: View: Show References Explorer

📋 Core Features

🎯 Smart Reference Search

Automatically find and organize all references to templates, behaviors, and forms across your project.

Organized Categories (Incremental Priority):

• 📝 Input Forms - Files with formatInput (highest priority)
• 📤 Output Forms - Files with formatOutput
• 📥 Input Templates - Files in /templates/input/ directories
• 📤 Output Templates - Files in /templates/output/ directories
• ⚡ Infusion - JavaScript/TypeScript files
• 🧠 Behaviors - Files with behavior in name (lowest priority)

Built-in Filters:

• 🏢 Customer Filter - Show only specific customer's files
• 🔍 Free Text Filter - Search within results by content
• 📄 Smart Exclusions - Test files (-test) automatically hidden

🔄 Advanced Features

• Find Form Usage - Trace dependency chains from templates to forms
• Progress Indicators - Native VS Code progress with cancellation
• Real-time Updates - File watchers keep results current
• Smart Caching - 20-50x faster searches after first run

🛠️ How to Use

Find All References

Right-click on template name → "Find References in Explorer"

• Purpose: Find ALL references across different file types
• Result: Organized by category (Forms → Templates → Infusion → Behaviors)
• Filters: Automatically cleared for fresh results

Find Form Dependencies

Right-click on template name → "Find Form Usage"

• Purpose: Trace which FORMS ultimately use this template
• Process: Select customer → Shows dependency chains
• Result: Tree view showing path from template to final forms

Using Filters

1. Customer Filter 🏢: Click button → Select customer from dropdown
2. Free Text Filter 🔍: Click button → Type search term
3. Clear Filters: Click "Clear All Filters" or run new search

🎯 Panel Controls

Toolbar Buttons:

• 🔄 Refresh - Reload current search results
• 🏢 Select Customer - Filter by specific customer
• 🔍 Free Text Filter - Search within current results
• 🗑️ Rebuild Cache - Reset search cache for fresh indexing

Information Display:

• Search Term - Shows what you're searching for
• Total Count - Number of references found
• Active Filters - Current customer/text filters applied
• Form Chains - Dependency paths for Form Usage searches

💡 Practical Examples

Example 1: Finding Template Usage

// File: itpRecordCoating.formatInput.json5
{
  overrides: {
    signaturesCollectionItem: 'dbctSignaturesCollectionItem'
    //                         ↑ Place cursor here
  }
}

Action: Right-click → "Find References in Explorer"
Result: All files using dbctSignaturesCollectionItem, organized by type

Example 2: Tracing Form Dependencies

// Template: commonSignatureTemplate.json5
{
  signature: {
    required: true,
    type: "string"
  }
}

Action: Right-click → "Find Form Usage" → Select "dbct"
Result: Tree showing which forms ultimately use this template

Example 3: Customer-Specific Search

1. Search for any template (e.g., "dbctSignatures")
2. Click 🏢 Customer Filter → Select "dbct"
3. Result: Only DBCT references visible

⚡ Performance & Caching

High-Performance Search

• First Search: 5-10 seconds (builds cache)
• Subsequent Searches: 0.1-0.5 seconds (uses cache)
• Auto-Updates: File changes automatically update cache
• Memory Optimized: Smart LRU eviction with 45MB budget

Cache Management

• Automatic: Cache builds and updates seamlessly
• Manual Rebuild: Use "🗑️ Rebuild Cache" if results seem stale
• Smart Filtering: Only indexes relevant file types
• Performance: 20-50x speed improvement over uncached search

Scope Optimization

Search is limited to specific CSV directories for maximum performance:

• behaviors/, en/, es/, json/, pt/, v2json/

🧪 Testing Your Setup

Basic Functionality Test:

1. Open dbctSignaturesCollectionItem.json5
2. Place cursor on any template name
3. Right-click → "Find References in Explorer"
4. Expected: References organized in categories

Filter Test:

1. After basic test, click 🏢 Customer Filter
2. Select "dbct" from dropdown
3. Expected: Only DBCT references visible

Form Usage Test:

1. Place cursor on template name
2. Right-click → "Find Form Usage" → Select customer
3. Expected: Tree showing dependency chains to forms

Cache Performance Test:

1. Run search, note timing
2. Run same search again
3. Expected: Dramatically faster second search

🔧 Troubleshooting

No Results Found:

• ✅ Verify cursor is on template name (not quotes)
• ✅ Check CSV directory configuration in VS Code settings
• ✅ Ensure file is in supported location

Slow Performance:

• ✅ Click 🗑️ Rebuild Cache to rebuild index
• ✅ Check that search scope includes your files
• ✅ Verify file watchers are working properly

Incorrect Categories:

• ✅ Files appear in highest priority category only (by design)
• ✅ Check file naming follows expected patterns
• ✅ Verify path structure matches template expectations

Missing References:

• ✅ Clear all filters to see full results
• ✅ Try "Find Form Usage" for dependency chains
• ✅ Rebuild cache if files recently changed

📈 Before vs After

⚙️ Technical Overview (Summary)

Cache System

• File Content Cache: High-performance with LRU eviction (45MB budget)
• Reference Index: Symbol reference caching with provider integration
• Graph Builder: Dependency chain building with cycle detection
• Coordination: Unified interface managing all cache components

Smart Architecture

• Incremental Updates: TextDocumentChangeEvent deltas for real-time updates
• Memory Management: Chunked rope structure for large files (>2MB)
• Provider Integration: VS Code language server integration with regex fallbacks
• Cancellation Support: User can cancel long-running operations

File Support

• Primary: JSON, JSON5 files
• Secondary: JavaScript, TypeScript files (for behaviors)
• Filtering: Automatic exclusion of test files and non-relevant files

🎉 Pro Tips

For Large Projects:

• Use Customer Filter early to focus scope
• Let cache build completely for best performance
• Use Find Form Usage for end-to-end dependency tracing

For Development:

• Find References for understanding usage patterns
• Find Form Usage for impact analysis before changes
• Use Free Text Filter to find specific implementations

For Performance:

• Keep frequently used files open in VS Code
• Allow cache to build fully on first use
• Use cancellation (ESC) for unwanted long searches

🆘 Need Help?

• Commands: All features accessible via right-click context menu
• Panel: References Explorer in Activity Bar (📚)
• Configuration: VS Code Settings → Search "vsconfig"
• Performance: Rebuild cache if results seem outdated

The References Explorer transforms complex template navigation into fast, organized, and intuitive workflows! 🚀