Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

Contracts and edge cases

Platform spec article

Contracts and edge cases

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”

Normative LSP workspace/executeCommand payloads and focusedProjectUri configuration. All URIs must be file:// URIs normalized per LSP URI rules.

focusedProjectUri

Section titled “focusedProjectUri”
Rule IDRule
F-01On language client start, extension must send initializationOptions.focusedProjectUri when a project is focused.
F-02LSP must accept deprecated initializationOptions.selectedProjectUri as an alias when focusedProjectUri is absent.
F-03On focus change without client restart, extension must notify via workspace/didChangeConfiguration with settings object { "beskid": { "focusedProjectUri": "<uri>" } } or the beskid.project configuration section equivalent documented in extension settings.
F-04When focusedProjectUri is set, LSP should prefer that manifest for workspace scan ordering and cached_compilation_context selection; when unset, behavior must match pre-explorer semantics (all roots).
F-05Extension must not restart the language client solely because focusedProjectUri changed.

Command transport

Section titled “Command transport”

All commands below use LSP method workspace/executeCommand with:

  • command: string identifier
  • arguments: JSON array; first element must be the args object when args are required

Errors must use LSP error codes; clients must surface message in a notification.

beskid.refreshWorkspace

Section titled “beskid.refreshWorkspace”
FieldValue
PurposeTrigger workspace rescan and diagnostic refresh (existing contract).
Arguments[] (empty)
Resultnull

Extension must invoke after manifest/lock watcher debounce and from command beskid.refreshWorkspace.

beskid.listWorkspaces

Section titled “beskid.listWorkspaces”

Discover every Workspace.proj under current LSP workspace roots (respecting scan skip dirs).

Arguments (optional object):

{
  "roots": ["file:///path/to/folder"]
}

When roots is omitted, LSP must use initialized workspace folders.

Result:

{
  "workspaces": [
    {
      "uri": "file:///…/Workspace.proj",
      "name": "corelib",
      "members": [
        {
          "id": "collections",
          "uri": "file:///…/packages/collections/Project.proj",
          "name": "collections"
        }
      ]
    }
  ]
}
FieldRequiredTypeMeaning
workspacesyesarrayOne entry per discovered workspace manifest
workspaces[].uriyesstringWorkspace.proj file URI
workspaces[].nameyesstringWorkspace name from manifest
workspaces[].membersyesarrayParsed workspace members
members[].idyesstringMember id from Workspace.proj
members[].uriyesstringMember Project.proj URI
members[].namenostringDisplay name; defaults to id when omitted

beskid.getWorkspaceSummary

Section titled “beskid.getWorkspaceSummary”

Arguments:

{
  "workspaceUri": "file:///…/Workspace.proj"
}

Result:

{
  "workspaceUri": "file:///…/Workspace.proj",
  "name": "corelib",
  "members": [
    {
      "id": "collections",
      "uri": "file:///…/Project.proj",
      "name": "collections",
      "projectName": "collections"
    }
  ],
  "registries": [
    {
      "alias": "default",
      "url": "https://registry.example/"
    }
  ]
}
FieldRequiredMeaning
registriesyesEffective registry URLs from workspace resolution rules (see compiler workspace contracts); used by package panel for default registry base
members[].projectNamenoParsed project.name when available

beskid.getProjectGraph

Section titled “beskid.getProjectGraph”

Arguments:

{
  "projectUri": "file:///…/Project.proj"
}

Result:

{
  "projectUri": "file:///…/Project.proj",
  "nodes": [
    {
      "id": "dep:corelib",
      "kind": "dependency",
      "label": "corelib",
      "manifestUri": "file:///…/Project.proj",
      "materializedRoot": "file:///…/.beskid/packages/corelib/1.0.0"
    }
  ],
  "edges": [
    { "from": "project", "to": "dep:corelib" }
  ],
  "unresolved": [
    {
      "dependencyName": "missing-pkg",
      "source": "registry",
      "descriptor": "missing-pkg@1.0.0"
    }
  ]
}
nodes[].kindMeaning
projectRoot project node (exactly one per result)
targetBuild target
dependencyResolved or declared dependency project
sourceRootSource directory

unresolved[] must mirror analysis UnresolvedDependencyNote (dependencyName, source, descriptor).

beskid.getProjectDependencies

Section titled “beskid.getProjectDependencies”

Merged view of manifest declarations and lock lines for one project.

Arguments:

{
  "projectUri": "file:///…/Project.proj"
}

Result:

{
  "projectUri": "file:///…/Project.proj",
  "declared": [
    {
      "name": "corelib",
      "version": null,
      "source": "registry",
      "registry": "default",
      "descriptor": "corelib"
    }
  ],
  "locked": [
    {
      "name": "corelib",
      "resolvedVersion": "1.2.0",
      "registry": "default",
      "checksum": "sha256:…",
      "materializedRoot": "file:///…/.beskid/packages/corelib/1.2.0"
    }
  ],
  "unresolved": []
}
ArrayMeaning
declaredEntries from Project.proj dependency tables
lockedEntries from Project.lock when present; empty when lock missing
unresolvedDeclared deps that could not be resolved or locked

locked[].resolvedVersion must match lockfile semantics in workspace and lock contracts.

Explorer-specific rules

Section titled “Explorer-specific rules”
IDRule
E-W01beskid.listWorkspaces must complete in O(roots × files) with scan skip dirs; must not build full compile graphs.
E-W02beskid.getProjectGraph may use build_project_graph_with_options from analysis; cycles must be represented as edges without infinite expansion in the tree UI.
E-W03When projectUri is outside workspace roots, LSP must return error InvalidParams with a clear message.
E-W04Extension command beskid.focusProject must set focusedProjectUri; beskid.clearFocus must clear it and notify LSP.
Section titled “Related topics”