Flow and algorithm

Platform spec article

Flow and algorithm

Back to Workspace and project explorer ◎ Open feature 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

• Feature
  Workspace and project explorer

  Parent feature hub

Purpose and scope

End-to-end sequences from extension activation through tree population and focus synchronization.

Activation and LSP start

sequenceDiagram
  participant VS as VS Code
  participant Ext as Extension
  participant LSP as beskid_lsp
  VS->>Ext: activate
  Ext->>Ext: read workspaceState.focusedProjectUri
  Ext->>LSP: start LanguageClient (initializationOptions.focusedProjectUri)
  LSP-->>Ext: initialized
  Ext->>LSP: executeCommand beskid.listWorkspaces
  LSP-->>Ext: workspaces[]
  Ext->>Ext: populate WorkspaceTreeProvider
  alt focusedProjectUri set
    Ext->>LSP: executeCommand beskid.getProjectGraph
    LSP-->>Ext: graph JSON
    Ext->>Ext: populate ProjectTreeProvider
  end

1. Extension must start the language client before populating trees (commands are server-backed).
2. If no focus is stored, extension may defer Project view population until auto-select or user picks a member.

Member selection flow

1. User activates a member node in beskidWorkspaceView.
2. Extension sets focusedProjectUri = member.uri.
3. Extension persists workspace state and sends configuration notification to LSP (no restart).
4. Extension refreshes beskidProjectView, outline, and package panel local section (parallel getProjectGraph + getProjectDependencies).
5. Status bar may show project name briefly (non-blocking).

Auto-select from editor

1. onDidChangeActiveTextEditor fires with document URI.
2. If beskid.project.autoSelectFromEditor is false, stop.
3. Resolve Project.proj for editor path; if none, stop.
4. If resolved URI equals current focus, stop.
5. Set focus and run member selection steps 3–4.

Debounced workspace refresh

1. File watcher fires (manifest, lock, .bd, or workspace.package.json).
2. Extension debounces (≥300ms coalescing).
3. executeCommand('beskid.refreshWorkspace').
4. Re-fetch beskid.listWorkspaces; if focus still valid, re-fetch graph and dependencies.
5. Fire onDidChangeTreeData on both providers.

Reveal in tree

Command	Behavior
beskid.revealInWorkspaceTree	Expand workspace containing focus; reveal member or workspace root
beskid.revealInProjectTree	Reveal focused Project.proj root and scroll to dependency/target node when arg node id provided

Both must be available from editor title/context when a Beskid file is active.

Verification notes

• Flow tests should mock LSP executeCommand and assert ordering: listWorkspaces before getProjectGraph on cold start.
• Changing focusedProjectUri must not appear in logs as a full language-client restart.

Related topics

• Design model
• Examples