# VS Code Extension — Context

This workspace contains everything that touches the VS Code host API. It consumes
`core/` and wires its output into the VS Code UI layer.

---

## What Lives Here

```
vscode-extension/
├── extension.js               ← Entry point — registers all providers and commands on activate()
└── src/
    ├── diagnostics.js         ← collectDiagnostics(): orchestrates validators, posts to DiagnosticCollection
    ├── hoverProvider.js       ← Hover cards: variable type, function signature, rule explanation
    ├── completionProvider.js  ← Completions: macro names with parameter hints
    ├── definitionProvider.js  ← Go to Definition: resolves declarations across include files
    ├── codeActionProvider.js  ← Quick Fixes: maps diagnostic codes to one-click corrections
    ├── templateProvider.js    ← File Templates: scaffolds new report and include files
    ├── config/
    │   └── standardsConfig.js ← Reads workspace settings (vscode.workspace.getConfiguration)
    ├── diagnostics/
    │   ├── diagnosticFactory.js   ← Wraps core factory; creates vscode.Diagnostic instances
    │   └── validationScheduler.js ← Debounces re-validation on document change events
    └── commands/
        ├── batchValidateTxtFolder.js ← acurity.validateTxtFolder command
        ├── discoveryReport.js        ← acurity.discoveryReport command
        └── setupWizard.js            ← acurity.setupWizard command
```

---

## VS Code API Conventions

- **Activation events** are declared in `package.json` under `activationEvents`. Add new ones
  there before relying on them in `extension.js`.
- **Providers** are registered in `extension.js` with `vscode.languages.register*`. Each
  provider file exports a single class implementing the relevant VS Code provider interface.
- **Commands** are registered in `extension.js` with `vscode.commands.registerCommand`.
  The command ID must match the entry in `package.json` → `contributes.commands`.
- **Configuration** is always read via `standardsConfig.js` — never call
  `vscode.workspace.getConfiguration` directly from a provider.
- **DiagnosticCollection** is owned by `diagnostics.js`. Providers do not write to it directly.

---

## Adding a New Quick Fix

1. Add the fix strategy to `core/src/diagnostics/quickFixCatalog.js` (rule ID → fix description).
2. Implement the `CodeAction` in `codeActionProvider.js`, keyed on the same rule ID.
3. Add a syntax test that exercises the fix (see `test/CONTEXT.md`).

## Adding a New Command

1. Add the command ID and title to `package.json` → `contributes.commands`.
2. Create `src/commands/yourCommand.js` exporting an async function.
3. Register it in `extension.js`: `vscode.commands.registerCommand('acurity.yourCommand', yourCommand)`.

---

## package.json Conventions

- `main` points to `vscode-extension/extension.js` (relative to `architect-language-tools/`).
- `engines.vscode` pins the minimum VS Code version — do not lower it without checking API
  compatibility for all providers.
- `contributes.configuration` declares all user-facing settings. Keep descriptions accurate
  and set sensible defaults.
- **Do not add entries to `dependencies`** without explicit review. `devDependencies` for
  build/packaging tooling is acceptable.

---

## Relationship to Core

This workspace depends on `core/` but `core/` must never depend on this workspace.
If you find yourself reaching into `vscode-extension/` from a `core/` file, stop —
that logic belongs either in `core/` (if it has no VS Code dependency) or here.
