Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

Design model

Platform spec article

Design model

Back to Workspace and project explorer Open feature in platform map

Spec standingStandard

Owner
Piotr Mikstacki
Submitter
Piotr Mikstacki

Purpose and scope

Section titled “Purpose and scope”

This article defines the data and UI model for Workspaces (beskidWorkspaceView) and Project (beskidProjectView) tree views, FocusedProjectState, and how they connect to LSP payloads.

Focused project state

Section titled “Focused project state”
FieldTypeMeaning
focusedProjectUristring (file URI)Canonical Project.proj URI driving outline, packages “This project”, and LSP ordering
workspaceUristring | nullParent Workspace.proj URI when the focused project is a workspace member
memberIdstring | nullWorkspace member id from Workspace.proj when applicable

The extension must persist focusedProjectUri in ExtensionContext.workspaceState under key beskid.focusedProjectUri and must push the same value to the LSP on change (see contracts).

Workspaces tree shape

Section titled “Workspaces tree shape”
flowchart TB
  subgraph workspacesView [beskidWorkspaceView]
    W1[Workspace root]
    W1 --> M1[Member: Project.proj]
    W1 --> M2[Member: ...]
    W1 --> WP[workspace.package.json hint]
  end
Node kindChildren sourceDefault action on click
Workspace rootbeskid.listWorkspaces → one entry per Workspace.projExpand/collapse
Membermembers[] on workspace entrySet focus to member uri; refresh project/outline/packages views
Registry hintStatic label when workspace.package.json exists beside Workspace.projOpen file in editor

Icons: workspace root root-folder; member folder-library; registry hint package.

Project tree shape

Section titled “Project tree shape”

Root must be the focused Project.proj node. Children must be built from beskid.getProjectGraph and must include:

Child sectionSourceNotes
Targetsnodes[] where kind === "target"One node per declared target
Dependenciesnodes[] / edges[] with kind === "dependency"Tooltip shows materialized path when present in graph metadata
Source foldersnodes[] where kind === "sourceRoot"Opens folder or first .bd on click
Unresolvedunresolved[]Warning icon; label includes dependency name and descriptor

Multi-root labeling

Section titled “Multi-root labeling”

When vscode.workspace.workspaceFolders.length > 1, any label that could collide across folders must use the format:

{workspaceFolderName} / {localLabel}

where workspaceFolderName is the VS Code folder name, not the on-disk path.

Auto-select from editor

Section titled “Auto-select from editor”

When setting beskid.project.autoSelectFromEditor is true (default true), the extension must on onDidChangeActiveTextEditor:

  1. Map the editor file path to a containing directory.
  2. Walk upward to find Project.proj (same discovery rules as CLI/LSP discover_project_file).
  3. If the project is a workspace member, set workspaceUri and memberId from beskid.getWorkspaceSummary when needed.
  4. Update focusedProjectUri without user confirmation unless the new project differs from focus and beskid.project.confirmAutoFocus is true (optional setting; default false).

File watchers

Section titled “File watchers”

The extension must register watchers (debounced, ≥300ms) for:

  • **/*.{bd,proj}
  • **/Project.lock
  • **/workspace.package.json

On fire: debounced beskid.refreshWorkspace, then refresh both tree providers.

Canonical references

Section titled “Canonical references”