.cursorrules

You are an expert VS Code extension developer. Follow established functional programming patterns and TypeScript best practices.

## Code Style & Architecture

**TypeScript Standards:**

- Use functional programming with `readonly` types and `Object.freeze()` for immutability
- Prefer factory functions over classes for component creation
- Write pure functions with explicit return type annotations
- Enable strict TypeScript: `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`

**Project Structure:**

- Keep `src/extension.ts` minimal - only register commands/providers
- Organize by feature: commands/, config/, ui/, providers/, utils/
- Separate core logic from VS Code API surface
- Use centralized type definitions in `types.ts`

**Code Quality:**

- Use modern linting/formatting tools (Biome, ESLint, Prettier)
- Freeze all exports to communicate immutability: `Object.freeze()`
- Apply dependency injection via factory functions and parameter objects
- Localize all user-facing strings with `vscode-nls` and `MessageFormat.file`

## Core Patterns

**Extension Activation:**

- Register all disposables through `context.subscriptions`
- Use factory functions for component creation
- Delegate heavy work to commands with progress indicators

**Configuration Management:**

- Read via `vscode.workspace.getConfiguration(namespace)`
- Return frozen configuration objects
- Support real-time changes with `onDidChangeConfiguration`

**Command Registration:**

```typescript
export function registerCommands(
  context: vscode.ExtensionContext,
  deps: Readonly<{
    /* injected dependencies */
  }>
): void;
```

**Error Handling:**

- Handle parse/processing errors gracefully with user feedback
- Return safe defaults (empty frozen arrays/objects) on errors
- Validate all user inputs to prevent injection attacks

## Performance & UX

**Performance:**

- Warn before processing large files with user confirmation
- Use `vscode.window.withProgress` for long-running operations
- Support cancellation tokens where applicable
- Minimize memory usage and avoid caching large content

**User Experience:**

- Provide subtle feedback (status bar) over notification spam
- Use localized strings for all user-facing text
- Support light/dark themes and accessibility
- Handle edge cases: no active editor, empty files, unknown types

## Localization System

**Manifest Prefix:** `manifest.*`

```json
{
  "displayName": "%manifest.ext.name%",
  "commands": [{ "title": "%manifest.command.title%" }]
}
```

**Runtime Prefix:** `runtime.*`

```typescript
const localize = nls.config({ messageFormat: nls.MessageFormat.file })();
const message = localize("runtime.error.message", "Error: {0}", details);
```

**File Structure:**

- `package.nls.json` - Base English strings
- `package.nls.{locale}.json` - Translations

## Testing & Debugging

**Testing:**

- Use Node.js built-in test runner with TypeScript support
- Structure code for testability with pure functions
- Organize test data with expected outputs
- Use coverage tools for quality assurance

**Debugging:**

- Use VS Code Output channels for local logging
- Structure logging with clear categories and levels
- Support debugging in development vs production modes

## Security & Privacy

- Default to privacy-first: no data collection unless explicitly enabled
- Use local-only logging when telemetry is enabled
- Validate all user inputs and file operations
- Support VS Code workspace trust and virtual workspace limitations

## Build & Tooling

**TypeScript Configuration:**

- Target modern JS (ES2020+) with CommonJS for VS Code compatibility
- Enable strict mode and additional safety checks
- Use proper module resolution and path mapping

**Code Standards:**

- Consistent indentation and formatting
- Meaningful variable names and function signatures
- Comprehensive error handling and edge case coverage
- Clear separation of concerns and single responsibility

Follow these patterns for maintainable, secure, and user-friendly VS Code extensions.