Flow and algorithm

Platform spec article

Flow and algorithm

Back to Snapshot and refresh contract ◎ 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-hub-authority Hub authority Accepted

   Hub authority

   Context

   One authority.

   Decision

   Hub owns snapshot/refresh MUST/SHOULD.

   Consequences

   IDE parity.

   Verification anchors

   beskid_lsp tests.

   Open full ADR page

2. 0002-invalidation-on-focus-and-manifest Invalidation Accepted

   Invalidation

   Context

   Stale snapshots.

   Decision

   Invalidate on focus, manifest, lock; debounce watchers.

   Consequences

   Config notification.

   Verification anchors

   session store.

   Open full ADR page

Articles

• Contracts and edge cases Strict guarantees for LSP snapshot lifecycle and refresh behavior. article Standard
• Design model Conceptual model for `Snapshot and refresh contract` and its subsystem boundaries. article Standard
• Examples Observable LSP refresh scenarios for snapshots and diagnostics. article Standard
• FAQ and troubleshooting Common LSP snapshot and refresh issues. article Standard
• Flow and algorithm End-to-end refresh flow for LSP workspace snapshots and diagnostics. article Standard
• Verification and traceability Tests and traceability for the LSP snapshot and refresh contract. article Standard

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 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
  Snapshot and refresh contract

  Parent feature hub

Open document refresh

sequenceDiagram
  participant Editor
  participant LSP as beskid_lsp
  participant Analysis as beskid_analysis
  Editor->>LSP: didChange (incremental)
  LSP->>LSP: apply_document_changes
  LSP->>LSP: text_hash unchanged?
  alt changed
    LSP->>Analysis: cached_compilation_context
    LSP->>Analysis: build_document_analysis_with_context
    LSP->>LSP: schedule_publish_diagnostics (120ms debounce)
  end
  LSP-->>Editor: publishDiagnostics

1. Apply LSP content changes to the open Document.
2. If text hash unchanged and version monotonic, skip re-analysis.
3. Otherwise rebuild DocumentAnalysisSnapshot using cached CompilationContext.
4. Coalesce diagnostic publish jobs per URI revision counter.

Workspace scan algorithm

scan_workspace(root, focused_project):

1. Walk directory tree, skipping .git, target, node_modules, .beskid, out, bin, obj, .vs.
2. Collect .bd and manifest paths; cap concurrent reads (MAX_CONCURRENT_READS = 24).
3. Call invalidate_compilation_cache before indexing when graph scope may have changed.
4. For each path, analyze_document or hydrate disk snapshot via set_disk_snapshot when not open.
5. Emit progress every 25 files or 200ms; finish with phase: idle.

Focused project URI steers which Project.proj seeds CompilationContext when a source file has ambiguous workspace membership.

External disk change

refresh_after_disk_change and hydrate_disk_after_close re-read closed files into workspace_index without clobbering open buffers. Manifest edits trigger cache invalidation then a full or scoped rescan from backend.rs configuration handlers.

Feature requests and snapshots

IDE features (completion, hover, definition, …) snapshot document text through protocol/request.rs helpers so handlers observe a consistent parse tree for the debounced generation.

Tests

compiler/crates/beskid_tests/src/analysis/resolve.rs covers resolver behavior consumed by LSP project context; extend LSP-specific tests when changing invalidation or scan skip rules.