Workspace and project explorer

Platform spec feature

Workspace and project explorer

Back to VS Code extension ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-lsp-backed-graph LSP graph Accepted

   LSP graph

   Context

   Parser drift.

   Decision

   Graph via LSP executeCommand.

   Consequences

   Thin wrappers.

   Verification anchors

   beskid_lsp handlers.

   Open full ADR page

2. 0002-focus-without-lsp-restart Focus without restart Accepted

   Focus without restart

   Context

   UX on focus.

   Decision

   didChangeConfiguration for focus; no LSP restart.

   Consequences

   Fast focus switch.

   Verification anchors

   Session invalidation.

   Open full ADR page

Articles

• Contracts and edge cases focusedProjectUri, LSP executeCommand JSON schemas, and explorer edge-case rules. article Standard Reviewed Thu May 21
• Decisions record (legacy index) Migration index for workspace and project explorer ADRs. article Standard Reviewed Fri May 22
• Design model Tree item model, focus state, icons, and multi-root labeling for workspace and project explorers. article Standard Reviewed Thu May 21
• Examples Corelib workspace and single-application explorer scenarios. article Standard Reviewed Thu May 21
• Flow and algorithm Activation, LSP init, tree refresh, auto-select, and reveal flows for workspace and project explorers. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 7 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  VS Code extension

  Parent area

• Feature
  Extension surface

  Parent integration hub

• Feature
  Workspace and lock contracts

  Workspace.proj and member paths

• Area
  LSP

  Graph executeCommands

What this feature specifies

Tree views and focus coordination for Beskid workspaces and the active Project.proj, backed by LSP executeCommands.

Implementation anchors

• beskid_vscode/src/workspace/WorkspaceTreeProvider.ts, ProjectTreeProvider.ts, FocusCoordinator.ts
• beskid_vscode/src/workspace/lspProjectApi.ts
• compiler/crates/beskid_lsp/src/project_explorer_api.rs

Contract statement

The workspace and project explorer exposes two Beskid activity-bar tree views. Workspaces lists every Workspace.proj under open VS Code folders and their declared members. Project shows the focused Project.proj (targets, dependencies, source folders) using LSP graph data—never duplicate manifest parsing in TypeScript.

Inputs and outputs

Input	Source
VS Code workspace folders	Editor
Focused project URI	beskid.project.autoSelectFromEditor, tree selection, or beskid.selectProject
LSP executeCommands	beskid.listWorkspaces, beskid.getWorkspaceSummary, beskid.getProjectGraph, beskid.getProjectDependencies

Output	Consumer
Focus change	LSP focusedProjectUri via init options + workspace/didChangeConfiguration
Tree labels / commands	VS Code UI

State model

• Focused project — canonical file:// URI of a Project.proj; persisted in workspace state as beskid.focusedProjectUri (legacy beskid.selectedProjectUri alias for one release).
• Workspace cache — refreshed on beskid.refreshWorkspace and file watchers for *.proj, Project.lock, workspace.package.json.

Algorithms and flow

1. Extension activates → start LSP with initializationOptions.focusedProjectUri.
2. Workspaces view calls beskid.listWorkspaces → render members; member click runs beskid.focusProject.
3. Project view reads focused URI → beskid.getProjectDependencies / beskid.getProjectGraph for children.
4. Optional auto-select: active editor path → nearest Project.proj when beskid.project.autoSelectFromEditor is true.
5. Focus change updates configuration without full LSP restart unless server binary settings change.

Decisions

No open decisions. D-TOOL-VSC-0001 (LSP-backed graph), 0002 (focus without LSP restart)—see adr/ and the ADRs tab.

Articles

• LSP graphLSP graph
• Contracts and edge casesfocusedProjectUri, LSP executeCommand JSON schemas, and explorer edge-case rules.
• Decisions record (legacy index)Migration index for workspace and project explorer ADRs.
• Design modelTree item model, focus state, icons, and multi-root labeling for workspace and project explorers.
• ExamplesCorelib workspace and single-application explorer scenarios.
• Flow and algorithmActivation, LSP init, tree refresh, auto-select, and reveal flows for workspace and project explorers.