diff --git a/.claude/docs/DATABASE.md b/.claude/docs/DATABASE.md index 090054772fc32..fe977297f8670 100644 --- a/.claude/docs/DATABASE.md +++ b/.claude/docs/DATABASE.md @@ -22,11 +22,11 @@ ### Helper Scripts -| Script | Purpose | -|--------|---------| -| `./coderd/database/migrations/create_migration.sh "migration name"` | Creates new migration files | -| `./coderd/database/migrations/fix_migration_numbers.sh` | Renumbers migrations to avoid conflicts | -| `./coderd/database/migrations/create_fixture.sh "fixture name"` | Creates test fixtures for migrations | +| Script | Purpose | +|---------------------------------------------------------------------|-----------------------------------------| +| `./coderd/database/migrations/create_migration.sh "migration name"` | Creates new migration files | +| `./coderd/database/migrations/fix_migration_numbers.sh` | Renumbers migrations to avoid conflicts | +| `./coderd/database/migrations/create_fixture.sh "fixture name"` | Creates test fixtures for migrations | ### Database Query Organization @@ -214,6 +214,5 @@ make lint - [ ] Migration files exist (both up and down) - [ ] `make gen` run after query changes - [ ] Audit table updated for new fields -- [ ] In-memory database implementations updated - [ ] Nullable fields use `sql.Null*` types - [ ] Authorization context appropriate for endpoint type diff --git a/.claude/docs/OAUTH2.md b/.claude/docs/OAUTH2.md index 9fb34f093042a..4716fc672a1e3 100644 --- a/.claude/docs/OAUTH2.md +++ b/.claude/docs/OAUTH2.md @@ -151,7 +151,6 @@ Before completing OAuth2 or authentication feature work: - [ ] Update RBAC permissions for new resources - [ ] Add audit logging support if applicable - [ ] Create database migrations with proper defaults -- [ ] Update in-memory database implementations - [ ] Add comprehensive test coverage including edge cases - [ ] Verify linting compliance - [ ] Test both positive and negative scenarios diff --git a/.claude/docs/TROUBLESHOOTING.md b/.claude/docs/TROUBLESHOOTING.md index 19c05a7a0cd62..28851b5b640f0 100644 --- a/.claude/docs/TROUBLESHOOTING.md +++ b/.claude/docs/TROUBLESHOOTING.md @@ -116,20 +116,33 @@ When facing multiple failing tests or complex integration issues: ### Useful Debug Commands -| Command | Purpose | -|---------|---------| -| `make lint` | Run all linters | -| `make gen` | Generate mocks, database queries | +| Command | Purpose | +|----------------------------------------------|---------------------------------------| +| `make lint` | Run all linters | +| `make gen` | Generate mocks, database queries | | `go test -v ./path/to/package -run TestName` | Run specific test with verbose output | -| `go test -race ./...` | Run tests with race detector | +| `go test -race ./...` | Run tests with race detector | ### LSP Debugging -| Command | Purpose | -|---------|---------| -| `mcp__go-language-server__definition symbolName` | Find function definition | -| `mcp__go-language-server__references symbolName` | Find all references | -| `mcp__go-language-server__diagnostics filePath` | Check for compilation errors | +#### Go LSP (Backend) + +| Command | Purpose | +|----------------------------------------------------|------------------------------| +| `mcp__go-language-server__definition symbolName` | Find function definition | +| `mcp__go-language-server__references symbolName` | Find all references | +| `mcp__go-language-server__diagnostics filePath` | Check for compilation errors | +| `mcp__go-language-server__hover filePath line col` | Get type information | + +#### TypeScript LSP (Frontend) + +| Command | Purpose | +|----------------------------------------------------------------------------|------------------------------------| +| `mcp__typescript-language-server__definition symbolName` | Find component/function definition | +| `mcp__typescript-language-server__references symbolName` | Find all component/type usages | +| `mcp__typescript-language-server__diagnostics filePath` | Check for TypeScript errors | +| `mcp__typescript-language-server__hover filePath line col` | Get type information | +| `mcp__typescript-language-server__rename_symbol filePath line col newName` | Rename across codebase | ## Common Error Messages @@ -197,6 +210,8 @@ When facing multiple failing tests or complex integration issues: - Check existing similar implementations in codebase - Use LSP tools to understand code relationships + - For Go code: Use `mcp__go-language-server__*` commands + - For TypeScript/React code: Use `mcp__typescript-language-server__*` commands - Read related test files for expected behavior ### External Resources diff --git a/.claude/docs/WORKFLOWS.md b/.claude/docs/WORKFLOWS.md index b846110d589d8..8fc43002bba7d 100644 --- a/.claude/docs/WORKFLOWS.md +++ b/.claude/docs/WORKFLOWS.md @@ -127,9 +127,11 @@ ## Code Navigation and Investigation -### Using Go LSP Tools (STRONGLY RECOMMENDED) +### Using LSP Tools (STRONGLY RECOMMENDED) -**IMPORTANT**: Always use Go LSP tools for code navigation and understanding. These tools provide accurate, real-time analysis of the codebase and should be your first choice for code investigation. +**IMPORTANT**: Always use LSP tools for code navigation and understanding. These tools provide accurate, real-time analysis of the codebase and should be your first choice for code investigation. + +#### Go LSP Tools (for backend code) 1. **Find function definitions** (USE THIS FREQUENTLY): - `mcp__go-language-server__definition symbolName` @@ -145,14 +147,49 @@ - `mcp__go-language-server__hover filePath line column` - Get type information and documentation at specific positions +#### TypeScript LSP Tools (for frontend code in site/) + +1. **Find component/function definitions** (USE THIS FREQUENTLY): + - `mcp__typescript-language-server__definition symbolName` + - Example: `mcp__typescript-language-server__definition LoginPage` + - Quickly navigate to React components, hooks, and utility functions + +2. **Find symbol references** (ESSENTIAL FOR UNDERSTANDING IMPACT): + - `mcp__typescript-language-server__references symbolName` + - Locate all usages of components, types, or functions + - Critical for refactoring React components and understanding prop usage + +3. **Get type information**: + - `mcp__typescript-language-server__hover filePath line column` + - Get TypeScript type information and JSDoc documentation + +4. **Rename symbols safely**: + - `mcp__typescript-language-server__rename_symbol filePath line column newName` + - Rename components, props, or functions across the entire codebase + +5. **Check for TypeScript errors**: + - `mcp__typescript-language-server__diagnostics filePath` + - Get compilation errors and warnings for a specific file + ### Investigation Strategy (LSP-First Approach) +#### Backend Investigation (Go) + 1. **Start with route registration** in `coderd/coderd.go` to understand API endpoints -2. **Use LSP `definition` lookup** to trace from route handlers to actual implementations -3. **Use LSP `references`** to understand how functions are called throughout the codebase +2. **Use Go LSP `definition` lookup** to trace from route handlers to actual implementations +3. **Use Go LSP `references`** to understand how functions are called throughout the codebase 4. **Follow the middleware chain** using LSP tools to understand request processing flow 5. **Check test files** for expected behavior and error patterns +#### Frontend Investigation (TypeScript/React) + +1. **Start with route definitions** in `site/src/App.tsx` or router configuration +2. **Use TypeScript LSP `definition`** to navigate to React components and hooks +3. **Use TypeScript LSP `references`** to find all component usages and prop drilling +4. **Follow the component hierarchy** using LSP tools to understand data flow +5. **Check for TypeScript errors** with `diagnostics` before making changes +6. **Examine test files** (`.test.tsx`) for component behavior and expected props + ## Troubleshooting Development Issues ### Common Issues diff --git a/CLAUDE.md b/CLAUDE.md index d5335a6d4d0b3..8b7fff63ca12f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,9 +47,19 @@ ### LSP Navigation (USE FIRST) +#### Go LSP (for backend code) + - **Find definitions**: `mcp__go-language-server__definition symbolName` - **Find references**: `mcp__go-language-server__references symbolName` - **Get type info**: `mcp__go-language-server__hover filePath line column` +- **Rename symbol**: `mcp__go-language-server__rename_symbol filePath line column newName` + +#### TypeScript LSP (for frontend code in site/) + +- **Find definitions**: `mcp__typescript-language-server__definition symbolName` +- **Find references**: `mcp__typescript-language-server__references symbolName` +- **Get type info**: `mcp__typescript-language-server__hover filePath line column` +- **Rename symbol**: `mcp__typescript-language-server__rename_symbol filePath line column newName` ### OAuth2 Error Handling diff --git a/site/CLAUDE.md b/site/CLAUDE.md index aded8db19c419..43538c012e6e8 100644 --- a/site/CLAUDE.md +++ b/site/CLAUDE.md @@ -1,5 +1,18 @@ # Frontend Development Guidelines +## TypeScript LSP Navigation (USE FIRST) + +When investigating or editing TypeScript/React code, always use the TypeScript language server tools for accurate navigation: + +- **Find component/function definitions**: `mcp__typescript-language-server__definition ComponentName` + - Example: `mcp__typescript-language-server__definition LoginPage` +- **Find all usages**: `mcp__typescript-language-server__references ComponentName` + - Example: `mcp__typescript-language-server__references useAuthenticate` +- **Get type information**: `mcp__typescript-language-server__hover site/src/pages/LoginPage.tsx 42 15` +- **Check for errors**: `mcp__typescript-language-server__diagnostics site/src/pages/LoginPage.tsx` +- **Rename symbols**: `mcp__typescript-language-server__rename_symbol site/src/components/Button.tsx 10 5 PrimaryButton` +- **Edit files**: `mcp__typescript-language-server__edit_file` for multi-line edits + ## Bash commands - `pnpm dev` - Start Vite development server @@ -42,10 +55,11 @@ ## Workflow -- Be sure to typecheck when you’re done making a series of code changes +- Be sure to typecheck when you're done making a series of code changes - Prefer running single tests, and not the whole test suite, for performance - Some e2e tests require a license from the user to execute - Use pnpm format before creating a PR +- **ALWAYS use TypeScript LSP tools first** when investigating code - don't manually search files ## Pre-PR Checklist