Copilot instructions

1# VS Code Copilot Instructions
2 
3## Project Overview
4 
5Visual Studio Code is built with a layered architecture using TypeScript, web APIs and Electron, combining web technologies with native app capabilities. The codebase is organized into key architectural layers:
6 
7### Root Folders
8- `src/`: Main TypeScript source code with unit tests in `src/vs/*/test/` folders
9- `build/`: Build scripts and CI/CD tools
10- `extensions/`: Built-in extensions that ship with VS Code
11- `test/`: Integration tests and test infrastructure
12- `scripts/`: Development and build scripts
13- `resources/`: Static resources (icons, themes, etc.)
14- `out/`: Compiled JavaScript output (generated during build)
15 
16### Core Architecture (`src/` folder)
17- `src/vs/base/` - Foundation utilities and cross-platform abstractions
18- `src/vs/platform/` - Platform services and dependency injection infrastructure
19- `src/vs/editor/` - Text editor implementation with language services, syntax highlighting, and editing features
20- `src/vs/workbench/` - Main application workbench for web and desktop
21  - `workbench/browser/` - Core workbench UI components (parts, layout, actions)
22  - `workbench/services/` - Service implementations
23  - `workbench/contrib/` - Feature contributions (git, debug, search, terminal, etc.)
24  - `workbench/api/` - Extension host and VS Code API implementation
25- `src/vs/code/` - Electron main process specific implementation
26- `src/vs/server/` - Server specific implementation
27- `src/vs/sessions/` - Agent sessions window, a dedicated workbench layer for agentic workflows (sits alongside `vs/workbench`, may import from it but not vice versa)
28 
29The core architecture follows these principles:
30- **Layered architecture** - from `base`, `platform`, `editor`, to `workbench`
31- **Dependency injection** - Services are injected through constructor parameters
32    - If non-service parameters are needed, they need to come before the service parameters
33- **Contribution model** - Features contribute to registries and extension points
34- **Cross-platform compatibility** - Abstractions separate platform-specific code
35 
36### Built-in Extensions (`extensions/` folder)
37The `extensions/` directory contains first-party extensions that ship with VS Code:
38- **Language support** - `typescript-language-features/`, `html-language-features/`, `css-language-features/`, etc.
39- **Core features** - `git/`, `debug-auto-launch/`, `emmet/`, `markdown-language-features/`
40- **Themes** - `theme-*` folders for default color themes
41- **Development tools** - `extension-editing/`, `vscode-api-tests/`
42 
43Each extension follows the standard VS Code extension structure with `package.json`, TypeScript sources, and contribution points to extend the workbench through the Extension API.
44 
45### Finding Related Code
461. **Semantic search first**: Use file search for general concepts
472. **Grep for exact strings**: Use grep for error messages or specific function names
483. **Follow imports**: Check what files import the problematic module
494. **Check test files**: Often reveal usage patterns and expected behavior
50 
51## Validating TypeScript changes
52 
53Choose validation based on the scope and risk of the change. Large-scale builds and typechecking can be slow, and consume significant resources, so minimize their use. Prefer existing editor or watch-task diagnostics and the smallest targeted tests that cover the changed behavior. Do not start build or watch tasks, run broad type checks, or make type checking a prerequisite for targeted tests solely as a completion ritual.
54 
55Run a targeted type check or build when you are not fully confident in the change, and the change is broad or cross-cutting, it affects build or type configuration, or another validation step reports a compilation problem. Useful commands include:
56 
57- `npm run typecheck-client` for the main sources under `src/`
58- `npm run gulp compile-extensions` for built-in extensions
59- `npm run typecheck` from the `build` folder for build tooling
60 
61Development compile tasks already type-check their inputs. Do not run `npm run typecheck-client` immediately before `npm run compile` or `npm run compile-client`; choose the command that covers the required validation. When tests only need fresh output files, use the fast one-shot `npm run transpile-client` instead of compiling.
62 
63Use `scripts/test.sh` (or `scripts\test.bat` on Windows) for unit tests and `scripts/test-integration.sh` (or `scripts\test-integration.bat` on Windows) for integration tests. Add a targeted selector such as `--grep` whenever possible. Run `npm run valid-layers-check` only when a change may affect module layering.
64 
65## Coding Guidelines
66 
67### Indentation
68 
69We use tabs, not spaces.
70 
71### Naming Conventions
72 
73- Use PascalCase for `type` names
74- Use PascalCase for `enum` values
75- Use camelCase for `function` and `method` names
76- Use camelCase for `property` names and `local variables`
77- Use whole words in names when possible
78 
79### Types
80 
81- Do not export `types` or `functions` unless you need to share it across multiple components
82- Do not introduce new `types` or `values` to the global namespace
83 
84### Comments
85 
86- Use JSDoc style comments for `functions`, `interfaces`, `enums`, and `classes`
87 
88### Strings
89 
90- Use "double quotes" for strings shown to the user that need to be externalized (localized)
91- Use 'single quotes' otherwise
92- All strings visible to the user need to be externalized using the `vs/nls` module
93- Externalized strings must not use string concatenation. Use placeholders instead (`{0}`).
94 
95### UI labels
96- Use title-style capitalization for command labels, buttons and menu items (each word is capitalized).
97- Don't capitalize prepositions of four or fewer letters unless it's the first or last word (e.g. "in", "with", "for").
98 
99### Designing UI
100- When creating, editing, or reviewing any visual surface, reason in **design terms, not pixels**: name the **feeling** (Calm, Focused, Consistent, Delightful), find the **principle** it breaks, then reach for the **move** (token/tier/ramp) that restores it. Describe a bug by its role/tier/ramp (e.g. "this overlay is rounded at the control tier"), not its number.
101- See the [`design-philosophy` skill](skills/design-philosophy/SKILL.md) for the full Values→Principles→Moves vocabulary, worked examples, and feedback guidance, and [design-tokens.instructions.md](instructions/design-tokens.instructions.md) for the token reference.
102 
103### Style
104 
105- Use arrow functions `=>` over anonymous function expressions
106- Only surround arrow function parameters when necessary. For example, `(x) => x + x` is wrong but the following are correct:
107 
108```typescript
109x => x + x
110(x, y) => x + y
111<T>(x: T, y: T) => x === y
112```
113 
114- Always surround loop and conditional bodies with curly braces
115- Open curly braces always go on the same line as whatever necessitates them
116- Parenthesized constructs should have no surrounding whitespace. A single space follows commas, colons, and semicolons in those constructs. For example:
117 
118```typescript
119for (let i = 0, n = str.length; i < 10; i++) {
120    if (x < 10) {
121        foo();
122    }
123}
124function f(x: number, y: string): void { }
125```
126 
127- Whenever possible, in top-level scopes, use `export function x(…) {…}` instead of `export const x = (…) => {…}`. One advantage of using the `function` keyword is that the stack trace shows a good name when debugging.
128 
129### Code Quality
130 
131- All files must include Microsoft copyright header
132- Prefer `async` and `await` over `Promise` and `then` calls
133- All user facing messages must be localized using the applicable localization framework (for example `nls.localize()` method)
134- Don't add tests to the wrong test suite (e.g., adding to end of file instead of inside relevant suite)
135- Look for existing test patterns before creating new structures
136- Use `describe` and `test` consistently with existing patterns
137- Prefer regex capture groups with names over numbered capture groups.
138- If you create any temporary new files, scripts, or helper files for iteration, clean up these files by removing them at the end of the task
139- Never duplicate imports. Always reuse existing imports if they are present.
140- When removing an import, do not leave behind blank lines where the import was. Ensure the surrounding code remains compact.
141- Do not use `any` or `unknown` as the type for variables, parameters, or return values unless absolutely necessary. If they need type annotations, they should have proper types or interfaces defined.
142- When adding file watching, prefer correlated file watchers (via fileService.createWatcher) to shared ones.
143- When adding tooltips to UI elements, prefer the use of IHoverService service.
144- Do not duplicate code. Always look for existing utility functions, helpers, or patterns in the codebase before implementing new functionality. Reuse and extend existing code whenever possible.
145- You MUST deal with disposables by registering them immediately after creation for later disposal. Use helpers such as `DisposableStore`, `MutableDisposable` or `DisposableMap`. Do NOT register a disposable to the containing class if the object is created within a method that is called repeatedly to avoid leaks. Instead, return an `IDisposable` from such method and let the caller register it.
146- You MUST NOT use storage keys of another component only to make changes to that component. You MUST come up with proper API to change another component.
147- Use `IEditorService` to open editors instead of `IEditorGroupsService.activeGroup.openEditor` to ensure that the editor opening logic is properly followed and to avoid bypassing important features such as `revealIfOpened` or `preserveFocus`.
148- Avoid using `bind()`, `call()` and `apply()` solely to control `this` or partially apply arguments; prefer arrow functions or closures to capture the necessary context, and use these methods only when required by an API or interoperability.
149- Avoid using events to drive control flow between components. Instead, prefer direct method calls or service interactions to ensure clearer dependencies and easier traceability of logic. Events should be reserved for broadcasting state changes or notifications rather than orchestrating behavior across components.
150- Service dependencies MUST be declared in constructors and MUST NOT be accessed through the `IInstantiationService` at any other point in time.
151 
152## Learnings
153- Minimize the amount of assertions in tests. Prefer one snapshot-style `assert.deepStrictEqual` over multiple precise assertions, as they are much more difficult to understand and to update.
154- Do not stub a global object (e.g. `(mainWindow as any).ResizeObserver = ...`) or use `any` casts to install fakes in tests. Instead, make the dependency injectable: add an optional constructor parameter on the production class that defaults to the real implementation (e.g. `targetWindow.ResizeObserver`), and have the test pass a fake that implements the real interface.
155