# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build Commands

- `npm run compile` - Compiles TypeScript for both client and server
- `npm run watch` - Watches for changes and recompiles automatically
- `npm run lint` - Runs ESLint on client and server TypeScript files
- `npm run vscode:prepublish` - Prepares extension for publishing (runs compile)
- `npm install` - Installs dependencies for root, client, and server

## Architecture Overview

This is a Visual Studio Code extension for daScript language support. It follows the Language Server Protocol (LSP) architecture with a client-server pattern:

### Client (`/client/`)
- **Extension Host**: `extension.ts` - Main entry point that activates the extension
- **Multi-workspace Support**: Creates separate language server instances for each workspace folder
- **Debug Adapter**: Implements daScript debugging with launch/attach configurations
- **Commands**: `commands.ts` - Workspace validation and cache clearing commands

### Server (`/server/`)
- **Language Server**: `server.ts` - Core LSP implementation with completion, diagnostics, hover, etc.
- **Completion Engine**: `completion.ts` - Complex completion logic for daScript types, functions, structs, enums
- **Validation Queue**: `validatingQueue.ts` - Manages concurrent file validation with capacity limits
- **Settings**: `dasSettings.ts` - Configuration management for daScript compiler settings

### Key Components

**Language Features**:
- Code completion with type-aware suggestions
- Hover information with type details
- Go-to-definition/declaration support
- Diagnostic reporting (errors/warnings)
- Document symbols and workspace symbols
- Inlay hints for types and parameters

**daScript Integration**:
- Spawns daScript compiler process for validation
- Parses compiler output for completion data
- Supports project files (*.das_project)
- Handles module requirements and dependencies
- Caching system for compilation results

**Debugging**:
- Launch configurations for running daScript files
- Attach to running daScript processes
- Support for profiling and stepping debugger
- Terminal integration for script execution

## Development Workflow

1. Run `npm install` to install all dependencies
2. Press Ctrl+Shift+B (or Cmd+Shift+B) to compile
3. Use F5 to launch Extension Development Host
4. Use "Attach to Server" debug configuration to debug language server

## Configuration

The extension reads daScript settings from VS Code configuration:
- `dascript.compiler` - Path to daScript compiler
- `dascript.project.*` - Project-specific settings
- `dascript.policies.*` - Language policy settings

## File Validation

The server maintains a validation queue system that:
- Limits concurrent validations based on `compilationConcurrency` setting
- Caches results when `storeCompilationData` is enabled
- Provides real-time diagnostics as files are edited

## Testing

Debug configurations are available for:
- Testing single files with dastest framework
- Testing entire workspace
- Profiling script execution

## Key Files to Understand

- `server/src/server.ts:80-83` - Server command handlers
- `server/src/completion.ts:929-936` - Core completion data structures
- `client/src/extension.ts:51-127` - Extension activation and client management
- `server/src/validatingQueue.ts:8-36` - Validation concurrency control