Vscode configuration validation

VS Code Extension Configuration Validation

Domain: VS Code extension development, configuration management, quality assurance
Complexity: Intermediate
Prerequisites: Understanding of VS Code extension manifest (package.json), TypeScript

Decision Table

Symptom	Root Cause	Fix
Config value not persisting	Key not in contributes.configuration	Register in package.json
Command "not found" error	Command not in contributes.commands	Add command declaration
View not rendering	View ID mismatch	Match id in viewsContainers/views
Context menu missing	when clause fails	Fix context key expression
Activation too late	Missing activation event	Add onCommand:* or onView:*
Runtime config error	Try-catch missing	Wrap config access in try-catch

Problem

VS Code extensions fail at runtime when:

• Configuration keys are updated without being registered in package.json
• Commands are invoked but not declared in manifest
• Views/webviews reference unregistered IDs
• Context keys are set but not documented

These misconfigurations don't cause compile-time errors and only surface when users interact with specific features.

Solution

Systematic validation of VS Code extension manifest against runtime code usage.

1. Configuration Registration Validation

Check: All workspace.getConfiguration().update() calls reference registered properties.

// ❌ WRONG - config key not registered
await vscode.workspace.getConfiguration('alex.skillRecommendations')
  .update('code-review.accepted', count + 1, ConfigurationTarget.Global);

// ✅ RIGHT - key registered in package.json or wrapped in try-catch
try {
  await vscode.workspace.getConfiguration('alex.skillRecommendations')
    .update('code-review.accepted', count + 1, ConfigurationTarget.Global);
} catch (error) {
  console.log(`Skip tracking: ${error}`);
}

Audit Pattern:

# Find all config.update() calls
grep -r "getConfiguration.*\.update\(" src/

# Cross-reference with package.json properties section
# Each update() key must exist in "configuration.properties"

2. Command Registration Validation

Check: All commands.registerCommand() calls match declared commands in manifest.

// Code registration
vscode.commands.registerCommand('alex.validateHeir', async () => {...});

// Must have package.json declaration
{
  "contributes": {
    "commands": [{
      "command": "alex.validateHeir",
      "title": "Validate as Heir Project"
    }]
  }
}

Audit Pattern:

# Find all command registrations
grep -r "registerCommand\(['\"]alex\." src/

# Extract command names and verify each exists in package.json

3. Configuration Read Validation

Check: All getConfiguration().get() calls match registered properties.

// This config read should have a registered property
const enabled = vscode.workspace.getConfiguration('alex.voice').get('enabled', false);

// Check package.json has "alex.voice.enabled"

Warning Pattern: Configuration reads with no defaults are risky:

// ⚠️ No fallback - will be undefined if not registered
const value = config.get('someKey');

// ✅ Better - always provide default
const value = config.get('someKey', defaultValue);

4. Error Handling Patterns

For Dynamic Configuration Keys (skill recommendations, user preferences):

Option A: Register schema with dynamic pattern (complex) Option B: Graceful try-catch (simple, recommended)

// Pattern: Non-critical dynamic config
async function trackUserPreference(key: string, value: any) {
  try {
    await vscode.workspace.getConfiguration('alex.dynamic')
      .update(key, value, ConfigurationTarget.Global);
  } catch (error) {
    // Log but don't fail - tracking is optional
    console.log(`[the AI assistant] Skipping preference tracking: ${error}`);
  }
}

For Critical Configuration:

// Pattern: Essential config must be registered
await vscode.workspace.getConfiguration('alex.globalKnowledge')
  .update('remoteRepo', repo, ConfigurationTarget.Global);
// No try-catch - failure should bubble up

Validation Checklist

Pre-Publish Review

• Search code for getConfiguration().update() calls
• Verify each updated key exists in package.json properties OR has try-catch
• Search for registerCommand() calls
• Verify each command exists in contributes.commands
• Check for dynamic config patterns (user tracking, etc.)
• Apply graceful degradation pattern for non-critical features

Automated Audit Script

Pseudocode: validate-manifest
1. Search src/**/*.ts for getConfiguration('section').update('key') calls
2. Load contributes.configuration.properties from package.json
3. For each config update found in source code:
   If the full key (section.key) is NOT in package.json properties:
     Flag as unregistered config write (potential runtime error)
4. Report all mismatches

$issues += "⚠️  $fullKey - not registered (verify try-catch exists)"

} }

if ($issues.Count -gt 0) { Write-Host "Configuration validation issues:" -ForegroundColor Yellow $issues | ForEach-Object { Write-Host $_ } exit 1 }

## Common Pitfalls

1. **Dynamic Configuration Keys**: User preferences, tracking counters
   - **Solution**: Either register dynamic schema or use try-catch pattern

2. **Namespaced Configuration**: `alex.skill.subkey.value`
   - **Solution**: Register full dotted path: `"alex.skill.subkey.value": {...}`

3. **Multi-Target Updates**: Workspace vs Global vs WorkspaceFolder
   - **Solution**: Test configuration across all scopes

4. **Configuration Migration**: Deprecated settings
   - **Solution**: Use `deprecationMessage` in property definition

## Real-World Example: Skill Recommendations

**Problem**: Tracking skill usage without bloating package.json with hundreds of dynamic keys.

**Solution**: Graceful degradation pattern
```typescript
async function trackRecommendation(skillId: string, accepted: boolean) {
  try {
    const context = 'alex.skillRecommendations';
    const key = `${skillId}.${accepted ? 'accepted' : 'dismissed'}`;
    const current = vscode.workspace.getConfiguration(context).get<number>(key, 0);
    await vscode.workspace.getConfiguration(context).update(
      key, 
      current + 1, 
      vscode.ConfigurationTarget.Global
    );
  } catch (error) {
    // Feature degrades gracefully - recommendations still work
    console.log(`[the AI assistant] Skipping recommendation tracking: ${error}`);
  }
}

Why This Works:

• Feature works with or without tracking
• No user-facing error for unregistered config
• Logging helps debug if tracking is important
• Simple implementation vs complex dynamic schema

Integration with Existing QA

Add to .github/instructions/extension-audit-methodology.instructions.md:

### Configuration Validation

Before each release:
1. Run `node scripts/release-preflight.cjs`
2. Review any warnings for try-catch coverage
3. Test configuration updates in clean VS Code instance
4. Verify error messages are user-friendly

Resources

• VS Code Extension Manifest
• Configuration API
• Package.json Contribution Points

---

Sources of Truth:

• Incident: Skill recommendations broken due to unregistered config (2026-02-15)
• Root Cause: alex.skillRecommendations.* keys not in package.json
• Fix: Try-catch wrapper in src/chat/skillRecommendations.ts