housekeeping
This commit is contained in:
@@ -1,118 +0,0 @@
|
||||
---
|
||||
id: PLN-0065
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: LSP Boundary and Module Scaffolding
|
||||
status: done
|
||||
created: 2026-05-05
|
||||
completed: 2026-05-05
|
||||
tags: [studio, lsp, api, boundary, modules, architecture]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Recreate `prometeu-lsp:prometeu-lsp-api` and `prometeu-lsp:prometeu-lsp-v1` with a structurally correct boundary that is ready for long-term maintenance, while intentionally keeping the initial server behavior minimal.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0032` locks that:
|
||||
|
||||
- `lsp-api` is an internal Studio boundary, not a mirror of the LSP protocol;
|
||||
- `lsp-v1` is the concrete LSP adapter and the only module allowed to depend on `LSP4J`;
|
||||
- the current mock server shape MUST NOT be treated as the product pattern;
|
||||
- wave 1 prioritizes architecture and lifecycle over semantic depth.
|
||||
|
||||
The repository already reserves `prometeu-lsp:*` in `settings.gradle.kts`, but the modules are currently empty shells after the cleanup.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Recreate Gradle/module structure for `prometeu-lsp-api` and `prometeu-lsp-v1`.
|
||||
- Define the minimal internal API contract for server lifecycle by project.
|
||||
- Establish package boundaries that keep protocol DTOs and `LSP4J` types out of `lsp-api`.
|
||||
- Add boundary-oriented tests or build checks where feasible.
|
||||
|
||||
### Excluded
|
||||
- Wiring the server into Studio project open/close.
|
||||
- Rich semantic behavior, diagnostics, definition, symbols, or incremental analysis.
|
||||
- Automation channel work for `compile/build/run/debug`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Full language feature implementation.
|
||||
- Any attempt to preserve compatibility with the legacy removed `prometeu-lsp`.
|
||||
- Transport changes in the VS Code extension.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Recreate the Gradle modules with explicit dependency ownership
|
||||
|
||||
**What:** Reintroduce the `prometeu-lsp-api` and `prometeu-lsp-v1` modules as clean boundaries.
|
||||
**How:** Restore the module directories and `build.gradle.kts` files, wire them in `settings.gradle.kts`, and keep dependencies explicit:
|
||||
|
||||
- `prometeu-lsp-api` depends only on stable internal modules it truly needs;
|
||||
- `prometeu-lsp-v1` depends on `prometeu-lsp-api`, `compiler` services it consumes, and `LSP4J`;
|
||||
- no other Studio module depends on `LSP4J`.
|
||||
|
||||
**File(s):** `settings.gradle.kts`, `prometeu-lsp/prometeu-lsp-api/build.gradle.kts`, `prometeu-lsp/prometeu-lsp-v1/build.gradle.kts`, affected root/module build files.
|
||||
|
||||
### Step 2 - Define the minimal internal lifecycle contract in `lsp-api`
|
||||
|
||||
**What:** Create the smallest stable API needed by the Studio host.
|
||||
**How:** Add internal contracts such as a project-scoped `bootServer(project)` and `shutdownServer(project)` surface plus the minimal supporting DTO/entity types required by that lifecycle. Keep the API transport-agnostic and free of protocol DTOs.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-api/src/main/java/**`.
|
||||
|
||||
### Step 3 - Define the adapter shape in `lsp-v1`
|
||||
|
||||
**What:** Establish the internal code organization of the concrete adapter.
|
||||
**How:** Create clear package slices inside `lsp-v1`, such as:
|
||||
|
||||
- lifecycle/bootstrap,
|
||||
- server host/transport,
|
||||
- protocol DTO mapping,
|
||||
- compiler-facing service bridge.
|
||||
|
||||
The implementation may stay behaviorally dumb, but the structure MUST already reflect the final responsibility split.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`.
|
||||
|
||||
### Step 4 - Add boundary conformance tests
|
||||
|
||||
**What:** Prevent architectural drift from day 1.
|
||||
**How:** Add tests or static checks that fail if:
|
||||
|
||||
- `lsp-api` imports `LSP4J`;
|
||||
- protocol DTOs leak into `lsp-api`;
|
||||
- non-`lsp-v1` Studio modules start importing `LSP4J`.
|
||||
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-api/src/test/java/**`, `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, or build-level checks if that is cleaner.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Verify the lifecycle contracts in `lsp-api` have deterministic defaults and null-safety.
|
||||
- Verify `lsp-v1` module-local bootstrap pieces can be instantiated without a running Studio shell.
|
||||
- Verify boundary checks catch `LSP4J` leakage.
|
||||
|
||||
### Integration Tests
|
||||
- Run a root or targeted Gradle build proving the new modules compile and coexist with `prometeu-studio` and `prometeu-app`.
|
||||
|
||||
### Manual Verification
|
||||
- Inspect the recreated module tree and confirm `lsp-api` contains no protocol or `LSP4J` types.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] `prometeu-lsp-api` and `prometeu-lsp-v1` exist again as active modules.
|
||||
- [x] `lsp-api` exposes only internal lifecycle-oriented contracts.
|
||||
- [x] `lsp-v1` is the only module allowed to depend on `LSP4J`.
|
||||
- [x] The new module structure expresses clear responsibility boundaries even with dumb behavior.
|
||||
- [x] Boundary conformance is covered by tests or equivalent build checks.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0032` accepted and normatively locked.
|
||||
- Current Gradle graph and module includes available for reactivation.
|
||||
|
||||
## Risks
|
||||
|
||||
- Reintroducing the modules too loosely can recreate the same ambiguity that killed the legacy stack.
|
||||
- An underspecified API can force churn later; an oversized API can lock the wrong shape too early.
|
||||
- Build-only enforcement may miss architectural drift unless the checks are explicit.
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
id: PLN-0066
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Project-Scoped LSP Server Lifecycle in Studio
|
||||
status: done
|
||||
created: 2026-05-05
|
||||
completed: 2026-05-05
|
||||
tags: [studio, lsp, lifecycle, projects, boot, shutdown]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Wire the new LSP server lifecycle into the Studio project lifecycle so a server starts when a project opens and stops when that project closes, without introducing a process-global LSP service.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0032` requires a project-scoped server lifecycle and explicitly rejects a global Studio-wide server. The current natural integration points are:
|
||||
|
||||
- `StudioProjectSession`
|
||||
- `StudioProjectSessionFactory`
|
||||
- `StudioWindowCoordinator`
|
||||
|
||||
These surfaces already own project startup and teardown flow and therefore are the correct place to consume `lsp-api`.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Add project-scoped LSP server ownership to the Studio project session lifecycle.
|
||||
- Boot the server during project open.
|
||||
- Shutdown the server during project close.
|
||||
- Preserve existing shell, packer, play/stop, and debug flows.
|
||||
|
||||
### Excluded
|
||||
- Rich semantic responses.
|
||||
- Automation channel work.
|
||||
- VS Code extension transport changes.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Cross-project shared server process management.
|
||||
- Multi-project pooling or server reuse.
|
||||
- Changing the overall launcher/window model.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Extend project session ownership to include the LSP lifecycle boundary
|
||||
|
||||
**What:** Make `StudioProjectSession` own the new project-scoped LSP service reference.
|
||||
**How:** Add the minimal `lsp-api` contract to `StudioProjectSession`, ensure it is initialized by `StudioProjectSessionFactory`, and guarantee shutdown on `close()`, including failure-safe teardown ordering.
|
||||
**File(s):** `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`, `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSessionFactory.java`, related tests.
|
||||
|
||||
### Step 2 - Trigger boot during project open flow
|
||||
|
||||
**What:** Start the LSP server as part of project initialization.
|
||||
**How:** Update the project-open sequence so the server boots after the project context is ready and before the project window is considered fully opened. Ensure failures surface as project-open failures instead of becoming silent background errors.
|
||||
**File(s):** `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`, possibly `prometeu-app/src/main/java/p/studio/AppContainer.java` and `prometeu-studio/src/main/java/p/studio/Container.java` if dependency injection changes are needed.
|
||||
|
||||
### Step 3 - Trigger shutdown during project close flow
|
||||
|
||||
**What:** Cleanly stop the project-bound server when the project closes.
|
||||
**How:** Ensure the existing project close path tears down the LSP service through the session close path, with no leaked socket listener or hanging background resources.
|
||||
**File(s):** `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`, `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`.
|
||||
|
||||
### Step 4 - Preserve current dumb connectivity semantics
|
||||
|
||||
**What:** Keep the initial server behavior intentionally simple while validating lifecycle.
|
||||
**How:** Wire the server so the VS Code extension can still connect over TCP, even if the server behavior remains a minimal handshake or stubbed capability set for now.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`, `tools/vscode-extension/src/extension.ts` only if configuration or expectations need adjustment.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Verify project session close calls LSP shutdown exactly once.
|
||||
- Verify boot failures are surfaced deterministically during project open.
|
||||
- Verify repeated close remains idempotent.
|
||||
|
||||
### Integration Tests
|
||||
- Run `prometeu-studio` tests covering project open/close lifecycle.
|
||||
- Add a focused integration test proving a project-scoped server is booted and then shut down.
|
||||
|
||||
### Manual Verification
|
||||
- Open a Studio project, confirm the server starts.
|
||||
- Close the project, confirm the server port is released and the process/resources terminate.
|
||||
- Connect via the existing VS Code extension and confirm the dumb server remains reachable.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] Opening a Studio project boots an LSP server for that project.
|
||||
- [x] Closing the project shuts down that server.
|
||||
- [x] The lifecycle is owned by project session boundaries, not global app startup.
|
||||
- [x] Existing non-LSP project flows remain operational.
|
||||
- [x] The current dumb connectivity workflow remains usable as a temporary implementation phase.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0032` accepted and normatively locked.
|
||||
- `PLN-0065` providing the new module and API boundary.
|
||||
|
||||
## Risks
|
||||
|
||||
- Startup ordering mistakes can make project open flaky or hide boot errors.
|
||||
- Shutdown ordering mistakes can leak ports or threads.
|
||||
- Lifecycle wiring can accidentally reintroduce global process ownership if the session boundary is not kept strict.
|
||||
@@ -1,100 +0,0 @@
|
||||
---
|
||||
id: PLN-0067
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Compiler-Backed Dumb LSP Server Baseline
|
||||
status: done
|
||||
created: 2026-05-05
|
||||
completed: 2026-05-05
|
||||
tags: [studio, lsp, compiler, baseline, protocol, vscode]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Establish a maintainable, compiler-backed baseline inside `lsp-v1` that keeps the server behavior deliberately simple while creating the seams required for later semantic layering.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0032` explicitly allows wave 1 to remain semantically thin, but it forbids keeping an ad hoc mock structure as the long-term coding pattern. The backend therefore needs a baseline that is:
|
||||
|
||||
- dumb in behavior when necessary,
|
||||
- but already correctly composed over `compiler` services,
|
||||
- and already structured for layered enrichment later.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Create compiler-facing service seams used by `lsp-v1`.
|
||||
- Provide a small, explicit set of LSP capabilities or responses that prove the adapter shape.
|
||||
- Keep the VS Code extension compatible with the current TCP model.
|
||||
- Document the temporary behavioral limits in code and tests.
|
||||
|
||||
### Excluded
|
||||
- Full diagnostics, definition, symbols, inlay hints, or multi-file semantic completeness.
|
||||
- Automation channel work.
|
||||
- Non-TCP transport experiments.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Matching the full final language feature set.
|
||||
- Recreating the deleted legacy `prometeu-lsp` behavior.
|
||||
- Optimizing for performance before the baseline structure is validated.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Define compiler-facing bridge services inside `lsp-v1`
|
||||
|
||||
**What:** Introduce explicit bridge classes or adapters between protocol handlers and `compiler`.
|
||||
**How:** Create narrow services inside `lsp-v1` that own calls into `compiler` entrypoints. Even if the first concrete responses are stubbed or partial, the protocol handlers must already call through these seams instead of embedding compiler knowledge everywhere.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`, relevant `prometeu-compiler` integration points when discoverable.
|
||||
|
||||
### Step 2 - Implement a minimal but structured capability slice
|
||||
|
||||
**What:** Keep the server intentionally dumb, but no longer structurally improvised.
|
||||
**How:** Choose a small capability surface such as `initialize`, `shutdown`, and one lightweight language feature or health response. The exact feature set may stay narrow, but the code must already follow the final layering:
|
||||
|
||||
- protocol request handling,
|
||||
- bridge service invocation,
|
||||
- result mapping.
|
||||
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`, potentially `tools/vscode-extension/src/extension.ts` if initialization expectations need tightening.
|
||||
|
||||
### Step 3 - Codify temporary behavior limits
|
||||
|
||||
**What:** Make the current limitations explicit instead of implicit.
|
||||
**How:** Add tests and lightweight documentation/comments that define the intentionally supported baseline behavior so future work can add capability in layers without guessing what the "mock" currently means.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, targeted source comments where they reduce ambiguity.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Verify protocol handlers call the correct bridge services.
|
||||
- Verify compiler bridge services can be instantiated and return stable baseline results.
|
||||
- Verify no handler bypasses the bridge layer to embed semantic logic ad hoc.
|
||||
|
||||
### Integration Tests
|
||||
- Run a targeted Studio/LSP integration proving the VS Code client can initialize against the dumb server.
|
||||
- Run compiler-related tests needed to validate the consumed service seams.
|
||||
|
||||
### Manual Verification
|
||||
- Connect from VS Code and confirm the server initializes and remains stable.
|
||||
- Confirm the limited capability set behaves predictably and does not masquerade as richer support than actually implemented.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] `lsp-v1` talks to `compiler` through explicit bridge services.
|
||||
- [x] The baseline server behavior remains intentionally simple but structurally clean.
|
||||
- [x] At least one minimal end-to-end capability slice proves the final layering.
|
||||
- [x] The extension can still connect over TCP without protocol regressions.
|
||||
- [x] Temporary semantic limits are explicit in tests and code structure.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0032` accepted and normatively locked.
|
||||
- `PLN-0065` for module/boundary setup.
|
||||
- `PLN-0066` for project-scoped lifecycle integration.
|
||||
|
||||
## Risks
|
||||
|
||||
- A "temporary" dumb server can calcify unless the seams are truly explicit and tested.
|
||||
- Over-stubbing can hide compiler integration issues that should be surfaced early.
|
||||
- Picking too many baseline features in this wave can dilute the architectural focus.
|
||||
@@ -1,119 +0,0 @@
|
||||
---
|
||||
id: PLN-0072
|
||||
ticket: frontend-semantic-host-projection-flexibility
|
||||
title: Frontend Semantic Host Projection Contract
|
||||
status: done
|
||||
created: 2026-05-06
|
||||
completed: 2026-05-06
|
||||
tags: [compiler, compiler-general, frontend, semantics, host-projection, vscode, pbs]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Introduce the canonical frontend-authored semantic host projection contract in compiler-general frontend metadata and migrate PBS to publish its first VS Code projection without weakening frontend-owned semantic vocabulary.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0034` locks that semantic vocabularies remain frontend-owned and canonical, while hosts such as VS Code consume declarative projection metadata authored by the frontend. The current semantic presentation work already establishes frontend-owned themes through `DEC-0033`, but semantic adaptation still lacks a structured host projection contract.
|
||||
|
||||
PBS is the first concrete frontend and therefore the first migration target, but the contract MUST remain compiler-general rather than PBS-shaped.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Evolve compiler/frontend metadata to publish declarative semantic host projection descriptors.
|
||||
- Define the contract shape for VS Code semantic token projection.
|
||||
- Migrate PBS to author VS Code projection metadata for its canonical semantic keys.
|
||||
- Add tests that lock the contract and prevent host-owned remapping logic from becoming the source of truth.
|
||||
|
||||
### Excluded
|
||||
- LSP transport changes.
|
||||
- VS Code extension runtime consumption changes.
|
||||
- Redesigning PBS canonical semantic keys to mimic VS Code categories.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Introducing a global rigid semantic taxonomy across frontends.
|
||||
- Making VS Code semantic token types the canonical frontend semantic contract.
|
||||
- Solving projection for every future host in the first wave.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Define compiler-general host projection metadata
|
||||
|
||||
**What:** Extend the frontend semantic metadata surfaces to carry host projection descriptors alongside canonical semantic keys.
|
||||
**How:** Add or evolve compiler-general model types so a frontend can declare, for each host projection entry:
|
||||
|
||||
1. the canonical frontend semantic key being projected,
|
||||
2. the target host identity,
|
||||
3. the host token type or equivalent target category,
|
||||
4. any host modifiers,
|
||||
5. fallback projection semantics when the host cannot represent the key exactly.
|
||||
|
||||
The contract MUST preserve the frontend semantic key as canonical and MUST treat projection as derivative metadata.
|
||||
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/models/**`, related frontend definition surfaces.
|
||||
|
||||
### Step 2 - Make projection rules operational and mechanically consumable
|
||||
|
||||
**What:** Turn the projection contract into an exact operational surface rather than an informal note.
|
||||
**How:** Define invariants, null/empty behavior, and lookup rules for projection descriptors, including:
|
||||
|
||||
1. host identifier semantics,
|
||||
2. duplicate or conflicting projection handling,
|
||||
3. missing projection behavior,
|
||||
4. fallback behavior representation,
|
||||
5. safe access patterns from `FrontendSpec`.
|
||||
|
||||
The result MUST allow host adapters to translate frontend-authored projection data mechanically without semantic reinterpretation.
|
||||
**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**`, associated compiler-general tests.
|
||||
|
||||
### Step 3 - Migrate PBS to author its first VS Code projection
|
||||
|
||||
**What:** Make PBS publish its VS Code semantic projection through the new contract.
|
||||
**How:** Update PBS frontend metadata so its canonical semantic keys remain unchanged while the frontend also declares how each key projects into VS Code semantic token types and modifiers. The authored projection MUST live in PBS frontend metadata and MUST NOT be reauthored inside the extension.
|
||||
**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**`, related PBS semantic presentation tests.
|
||||
|
||||
### Step 4 - Lock the contract with tests
|
||||
|
||||
**What:** Prevent future drift toward host-owned semantic policy.
|
||||
**How:** Add tests that assert:
|
||||
|
||||
1. frontends publish projection descriptors through compiler-general metadata,
|
||||
2. PBS canonical keys remain frontend-owned,
|
||||
3. PBS VS Code projection resolves mechanically from frontend metadata,
|
||||
4. no global repository-wide rigid semantic taxonomy is introduced as the canonical contract.
|
||||
|
||||
**File(s):** compiler-general and PBS test suites.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Validate projection model invariants, including required frontend key linkage and host target fields.
|
||||
- Validate `FrontendSpec` safely exposes host projection metadata.
|
||||
- Validate missing and duplicate projection handling.
|
||||
|
||||
### Integration Tests
|
||||
- Run targeted compiler and PBS tests proving host projection metadata compiles, resolves, and remains discoverable through frontend definitions.
|
||||
|
||||
### Manual Verification
|
||||
- Inspect PBS frontend metadata and confirm the VS Code projection is authored there rather than in host adapter code.
|
||||
- Confirm canonical PBS semantic keys remain readable and unchanged in ownership terms.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Compiler-general frontend metadata publishes declarative host projection descriptors.
|
||||
- [ ] The contract preserves canonical frontend semantic keys as the source of truth.
|
||||
- [ ] The contract supports a VS Code projection without forcing a global rigid taxonomy.
|
||||
- [ ] PBS authors its VS Code semantic projection through the new contract.
|
||||
- [ ] Tests lock the contract against host-owned semantic remapping drift.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0034` accepted and normatively locked.
|
||||
- `DEC-0033` accepted where semantic presentation metadata already exists and may need coordinated evolution.
|
||||
|
||||
## Risks
|
||||
|
||||
- Overfitting projection fields to PBS or to VS Code would weaken future frontend flexibility.
|
||||
- Allowing ambiguous projection semantics would push semantic authorship back into adapters.
|
||||
- Collapsing canonical keys into host-shaped aliases would violate `DEC-0034`.
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
id: PLN-0073
|
||||
ticket: frontend-semantic-host-projection-flexibility
|
||||
title: LSP Semantic Host Projection Transport
|
||||
status: done
|
||||
created: 2026-05-06
|
||||
completed: 2026-05-06
|
||||
tags: [lsp, compiler, frontend, semantics, host-projection, vscode, protocol]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Transport canonical frontend semantic vocabulary and frontend-authored VS Code host projection metadata through the Prometeu LSP boundary without normalizing semantic meaning inside the transport layer.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0034` requires LSP to carry both canonical frontend semantic keys and frontend-authored host projection metadata, while preserving the ownership boundary between frontend semantics and host adaptation. `DEC-0033` already introduced frontend-authored visual themes through the LSP handshake; semantic host projection must now follow the same ownership model.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Extend LSP-facing baseline message models to carry semantic host projection metadata.
|
||||
- Update the compiler-backed language service bridge to resolve and expose that metadata from frontend definitions.
|
||||
- Update the LSP protocol mapper to publish the transported metadata to the VS Code extension.
|
||||
- Add tests that prove canonical keys and projection metadata are both preserved across transport.
|
||||
|
||||
### Excluded
|
||||
- Defining the compiler-general projection contract itself.
|
||||
- Applying the projection inside the VS Code extension.
|
||||
- Redesigning semantic token classification logic beyond what is needed to expose projection metadata.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Performing semantic normalization inside the LSP layer.
|
||||
- Collapsing frontend semantic keys into host token types in baseline message models.
|
||||
- Introducing host-specific semantic rules into `lsp-api` that belong to frontend metadata.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Extend baseline transport models for semantic projection
|
||||
|
||||
**What:** Add baseline message shapes that can carry semantic host projection metadata.
|
||||
**How:** Evolve LSP-facing DTOs so the server description or related handshake payload can transport:
|
||||
|
||||
1. frontend language identity,
|
||||
2. canonical frontend semantic keys,
|
||||
3. one or more host projection entries for VS Code,
|
||||
4. any fallback metadata required by the projection contract.
|
||||
|
||||
The transport model MUST preserve canonical frontend keys explicitly rather than flattening everything into host token types.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-api/src/main/java/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`.
|
||||
|
||||
### Step 2 - Resolve transport payload from compiler frontend metadata
|
||||
|
||||
**What:** Make the language service bridge expose semantic host projection metadata from the frontend contract.
|
||||
**How:** Update compiler-backed bridge code to read canonical semantic keys plus VS Code projection descriptors from the frontend definition and map them into the baseline transport payload without reinterpreting semantic meaning.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`.
|
||||
|
||||
### Step 3 - Publish the projection payload through the handshake
|
||||
|
||||
**What:** Make the VS Code client able to receive semantic projection metadata at initialization time.
|
||||
**How:** Update the protocol mapping layer so the initialize result transports canonical semantic keys and VS Code projection metadata through the agreed experimental surface or another current handshake surface, while keeping semantic theming transport from `DEC-0033` intact and coherent.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/**`, related server description surfaces.
|
||||
|
||||
### Step 4 - Lock transport behavior with tests
|
||||
|
||||
**What:** Prevent future drift toward semantic normalization inside LSP.
|
||||
**How:** Add tests that assert:
|
||||
|
||||
1. canonical frontend semantic keys survive transport,
|
||||
2. VS Code projection entries survive transport,
|
||||
3. payload structure remains mechanically consumable by the extension,
|
||||
4. the transport layer does not replace frontend keys with host token categories.
|
||||
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, `prometeu-lsp/prometeu-lsp-api` tests if present.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Validate mapping from frontend projection metadata into baseline transport DTOs.
|
||||
- Validate transport serialization of canonical keys plus projection entries.
|
||||
|
||||
### Integration Tests
|
||||
- Run targeted `lsp-v1` tests proving the server handshake exposes both semantic themes and semantic host projection coherently.
|
||||
|
||||
### Manual Verification
|
||||
- Inspect the initialize payload and confirm that frontend semantic keys and VS Code projection metadata are both visible.
|
||||
- Confirm no layer in LSP rewrites canonical semantic keys into a mandatory host taxonomy.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] LSP transport models carry canonical frontend semantic keys and VS Code projection metadata together.
|
||||
- [ ] The compiler-backed bridge resolves that metadata directly from frontend definitions.
|
||||
- [ ] The initialize payload exposes the metadata mechanically to the extension.
|
||||
- [ ] Tests lock the transport layer against semantic normalization drift.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0034` accepted and normatively locked.
|
||||
- `PLN-0072` completes the compiler/frontend projection contract.
|
||||
- `DEC-0033` transport conventions remain in force for visual theme payloads.
|
||||
|
||||
## Risks
|
||||
|
||||
- Reusing visual theme payload structures carelessly could blur the boundary between visual and semantic contracts.
|
||||
- Flattening transport too aggressively could erase canonical frontend key identity.
|
||||
- Excessive protocol specialization could make future hosts harder to add.
|
||||
@@ -1,109 +0,0 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user