vscode-cosmosdb

# GitHub Copilot Instructions for vscode-cosmosdb

## Critical Build Commands

| Command                | Purpose                                                      |
| ---------------------- | ------------------------------------------------------------ |
| `npm run build`        | **Build the project** (use this, NOT `npm run compile`)      |
| `npm run lint`         | Check for linting errors                                     |
| `npm run prettier-fix` | Format code                                                  |
| `npm run l10n`         | Update localization files after changing user-facing strings |

> **NEVER use `npm run compile`** - always use `npm run build` to build the project.

## Code Style

- **Wrap comments at 120 characters**, the same as the code line width — do **not** wrap comments at 80. This applies to `//` line comments and `/* */` block comments. When reflowing, preserve URLs on their own line, blank `//` paragraph separators, and lint directives (e.g. `// oxlint-disable-next-line ...`).
- **Break comment lines at logical boundaries, not greedily at the character limit.** Prefer breaks at the end of a sentence or clause so each line reads as a coherent unit, and keep the lines reasonably balanced. Never leave a dangling orphan line with just a word or two (e.g. a lone `// 3).` or `// path.`); pull an earlier word down so the last line is substantial.
- The repository is formatted with **oxfmt** (`npm run prettier-fix`), not Prettier. Never run `npx prettier` — it uses different defaults (e.g. quote style) and will diverge from the repo format.

## Localization

- Do **not** make direct changes to localization files inside the `l10n/` (e.g., `bundle.l10n.json`, `bundle.l10n.[lang].json`, etc.) folder or `package.[lang].nls.json` files (e.g., `package.nls.de.json`, `package.nls.fr.json`, etc.).
- To update strings used in `package.json`, modify `package.nls.json` only. Do **not** update the actual translation files.
- After modifying any localizable strings, always run `npm run l10n` to update strings.
- Each `l10n.t()` translation key (the template string) must be **500 characters or fewer**. If a string exceeds this limit, split it into multiple separate `l10n.t()` calls and concatenate them (e.g., `l10n.t('Part one.') + l10n.t('Part two.')`).
- **Do not wrap non-translatable content in `l10n.t()`.** If a string has no translatable words after removing `{placeholders}`, drop the wrapper and use a plain template literal instead. Examples: `` `${percent}%` `` (not `l10n.t('{percent}%')`), `` `${label} — ${share}` `` (not `l10n.t('{label} — {share}')`). Pure symbols/units/format strings gain nothing from localization.
- **Keep decorative symbols out of the translation key.** Emoji and other decoration should be concatenated in code, not embedded in the key — e.g. `'❌ ' + l10n.t('Command failed:')`, not `l10n.t('❌ Command failed:')`.
- **Do not hardcode punctuation that is locale-dependent.** In particular, keep a trailing colon **inside** the translated string (e.g. `l10n.t('Database:')`), do **not** rewrite it as `l10n.t('Database') + ':'`. Colon spacing/glyph varies by locale (French uses a narrow no-break space `Type :`, CJK uses fullwidth `：`), so translators must control it.
- Distinguish **label-colon** from **sentence-colon**: a trailing colon that is natural sentence punctuation introducing following detail (e.g. `l10n.t('The query has syntax errors:')`) is fine and should be left as-is; it is not the same anti-pattern as a short UI label.
- When auditing keys, the source-of-truth catalog of all extracted `l10n.t()` template strings is `l10n/bundle.l10n.json` (regenerated by `npm run l10n`).

## Accessibility Skill Routing

- When implementing or modifying UI in React/Fluent UI webviews (for example under `src/webviews/`), use the `accessibility-aria-expert` skill.
- Apply the skill for ARIA labeling, tooltip accessibility, keyboard/focus behavior, status announcements, and dialog focus management.
- Keep all user-facing accessibility messages localizable and follow the Localization rules above.

## Telemetry Skill Routing

- When adding, modifying, or reviewing telemetry — any `callWithTelemetryAndErrorHandling` call, any `context.telemetry.properties`/`measurements` assignment, any helper that mutates an `IActionContext` to record stats, or any new telemetry event name — use the `telemetry-best-practices` skill.
- Apply the skill specifically to verify that no PII/EUII (file names, paths, resource names, IDs, queries, free-form user input, raw error messages) is emitted, and that properties vs. measurements, naming, and error categorization follow the repo conventions.

## Validation Before Finishing

Before finishing work, agents **must** run the following steps in order:

> **Verify every command's exit code.** A command has passed only when its process exits with code `0`; seeing the npm command
> banner or no error output is not sufficient. Some tools in this repository can terminate silently with exit code `255`.
> When the execution tool does not report the exit code reliably, capture and print it explicitly, and fail the shell command
> when it is nonzero. Do not continue to the next validation step after a nonzero exit.

1. **Localization** — If any user-facing strings were added, modified, or removed, run:
   ```bash
   npm run l10n
   ```
2. **Formatting** — Run oxfmt and verify that it exits with code `0`:
   ```bash
   npm run prettier-fix
   ```
   Do not infer success from a clean `git status`: the formatter may have exited before processing files.
3. **Linting** — Run the complete lint suite to confirm there are no linting errors:
   ```bash
   npm run lint
   ```
4. **Build** — Run all configured TypeScript build targets:
   ```bash
   npm run build
   ```

> **An agent must not finish or terminate until every applicable step above has been run and its zero exit code verified.**
> Skipping these steps or trusting output without checking the process result leads to CI failures.