110 lines
5.9 KiB
Markdown
110 lines
5.9 KiB
Markdown
---
|
|
id: PLN-0074
|
|
ticket: frontend-semantic-host-projection-flexibility
|
|
title: VS Code Semantic Host Projection Adapter
|
|
status: done
|
|
created: 2026-05-06
|
|
completed: 2026-05-06
|
|
tags: [vscode, extension, frontend, semantics, host-projection, adapter]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Make the VS Code extension consume frontend-authored semantic host projection metadata mechanically so semantic highlighting behavior no longer depends on extension-owned assumptions about frontend semantic key names.
|
|
|
|
## Background
|
|
|
|
`DEC-0034` makes the frontend semantic vocabulary canonical and requires VS Code adaptation to follow frontend-authored projection metadata rather than an extension-owned taxonomy. `DEC-0033` already moved visual theme ownership into frontend-authored runtime payloads; the semantic adapter must now follow the same model.
|
|
|
|
The current extension still contains assumptions about semantic token naming and package-level declarations that do not fully reflect frontend-authored projection data.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Consume semantic host projection payload from the LSP handshake.
|
|
- Translate frontend-authored VS Code projection descriptors into the extension's semantic token registration and runtime theme application flow.
|
|
- Reduce extension-owned semantic assumptions to the minimum static structure the VS Code platform requires.
|
|
- Add tests or verification hooks that prove the adapter follows frontend-authored projection data mechanically.
|
|
|
|
### Excluded
|
|
- Inventing or redefining canonical semantic meaning inside the extension.
|
|
- Reworking compiler semantic classification beyond consuming the delivered keys and projections.
|
|
- Solving projection for non-VS Code hosts.
|
|
|
|
## Non-Goals
|
|
|
|
- Making the extension the owner of semantic taxonomy policy.
|
|
- Hardcoding PBS-specific semantic mapping logic as the authoritative source.
|
|
- Guaranteeing a perfect one-to-one rendering match with Studio for every frontend key.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Update extension-side semantic projection models
|
|
|
|
**What:** Add extension-side runtime shapes for the transported semantic projection payload.
|
|
**How:** Extend the VS Code extension client code so it can read and store:
|
|
|
|
1. canonical frontend semantic keys,
|
|
2. VS Code projection entries per key,
|
|
3. fallback metadata if present,
|
|
4. any language-scoped identity needed to apply the projection safely.
|
|
|
|
These runtime shapes MUST reflect transported frontend-authored metadata rather than a hand-maintained extension mapping table.
|
|
**File(s):** `tools/vscode-extension/src/**`, generated `out/**` mirror as needed.
|
|
|
|
### Step 2 - Apply projection mechanically in the semantic adapter path
|
|
|
|
**What:** Make the extension derive VS Code-facing semantic behavior from the transported projection.
|
|
**How:** Update extension logic so semantic token registration, selectors, and any runtime semantic color rule generation consume the frontend-authored projection entries. The adapter MUST treat missing projection data as a fallback condition, not as permission to reauthor semantic meaning broadly in extension code.
|
|
**File(s):** `tools/vscode-extension/src/extension.ts`, related extension helper modules if introduced, generated `out/**` mirror as needed.
|
|
|
|
### Step 3 - Minimize static package-level semantic assumptions
|
|
|
|
**What:** Reduce static `package.json` semantic declarations to the minimum platform-required scaffolding.
|
|
**How:** Audit the extension manifest and runtime so static declarations remain only where VS Code requires them structurally. Any semantic mapping policy that can be expressed by frontend-authored projection data MUST move out of the manifest and into runtime translation logic.
|
|
**File(s):** `tools/vscode-extension/package.json`, `tools/vscode-extension/src/**`.
|
|
|
|
### Step 4 - Lock adapter behavior with tests and verification
|
|
|
|
**What:** Prevent regression toward extension-owned semantic policy.
|
|
**How:** Add tests or targeted verification code that assert:
|
|
|
|
1. the adapter reads frontend-authored projection payloads,
|
|
2. semantic rules derive from projection data rather than hardcoded PBS assumptions,
|
|
3. fallback paths stay bounded and explicit,
|
|
4. frontend projection updates do not require extension semantic remapping edits for ordinary token adjustments.
|
|
|
|
**File(s):** extension test surfaces if present, otherwise targeted runtime assertions and documented manual verification paths.
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Validate parsing of semantic projection payloads from the initialize response.
|
|
- Validate transformation from projection entries into VS Code semantic token rule inputs.
|
|
|
|
### Integration Tests
|
|
- If extension test infrastructure exists, verify that a mock initialize payload drives semantic adapter behavior without code-level remapping tables.
|
|
|
|
### Manual Verification
|
|
- Reload the extension and inspect runtime behavior with a PBS project to confirm semantic highlighting is driven by transported projection data.
|
|
- Confirm that a frontend-authored projection change would only require frontend/LSP updates, not new semantic mapping logic in the extension.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The extension consumes canonical semantic keys and VS Code projection metadata from the LSP handshake.
|
|
- [ ] Semantic adapter behavior derives mechanically from transported projection data.
|
|
- [ ] Static extension manifest assumptions are reduced to platform-required scaffolding.
|
|
- [ ] The extension no longer acts as the authoritative source of frontend semantic mapping policy.
|
|
|
|
## Dependencies
|
|
|
|
- `DEC-0034` accepted and normatively locked.
|
|
- `PLN-0073` completes LSP transport of semantic host projection metadata.
|
|
- `DEC-0033` dynamic visual theme translation remains in place and coherent with semantic adaptation.
|
|
|
|
## Risks
|
|
|
|
- VS Code manifest constraints may still require some static declarations, and those boundaries must stay explicit.
|
|
- Weak fallback rules could accidentally recreate extension-owned semantic policy.
|
|
- Failure to update generated extension output alongside source would leave the runtime out of sync in the current local environment.
|