Skip to content

add trace promotion for error bundle diagnostics - #3240

Open
DaliVana wants to merge 1 commit into
zigtools:masterfrom
DaliVana:promote-reference-traces
Open

add trace promotion for error bundle diagnostics#3240
DaliVana wants to merge 1 commit into
zigtools:masterfrom
DaliVana:promote-reference-traces

Conversation

@DaliVana

@DaliVana DaliVana commented Aug 6, 2026

Copy link
Copy Markdown

Hello, this implements "trace promotion" (zigtools/zls#3239) and (zigtools/zls#2018): when a compile error's primary location is outside the workspace (standard library, dependencies in the package cache, or generated files in cache directories), the diagnostic is reported at the innermost reference trace location that is inside the workspace. The line where user code handed off to the library. Full fidelity is preserved through LSP relatedInformation:

  1. the original error location (error occurred here),
  2. the error's notes in their original order, untruncated,
  3. the remaining reference trace entries (referenced by '').

A new promote_reference_traces config option (default: true) restores the raw locations when disabled.

Why
Errors in comptime-heavy code often point into std (e.g. std.debug.print("{s}", .{42}) fails inside std/fmt.zig). ZLS published those diagnostics under the library file's URI — a file the user typically never has open — and discarded the reference trace during conversion, making the error effectively invisible in the editor.

How

  • Promotion happens at conversion time in DiagnosticsCollection; the stored ErrorBundle stays pristine, so other consumers (e.g. code_actions.zig, which reads src_loc spans directly) are unaffected, and toggling the option is lossless.
  • The workspace predicate resolves against the bundle's src_base_path (the build root) and reuses the same exclusion rules as DocumentStore.loadDirectoryRecursive (hidden directories, zig-cache, zig-pkg), using std.Io.Dir.path.isSep for platform-correct separator handling.
  • ErrorBundle has no public API for reading reference traces, so a small iterator walks the entries trailing each SourceLocation in extra; a comptime assertion guards the layout assumption (every field 32-bit) so upstream changes fail at compile time instead of misparsing.
  • collectUrisFromErrorBundle also collects the promoted URI so the user's file is republished, and still collects the original URI so stale diagnostics get cleared.
  • Promotion is skipped when src_base_path is null (a promoted relative path could not be resolved to a URI) and degrades gracefully to the original location when the trace never reaches workspace code (including truncated traces ending in the "hidden references" sentinel).
  • Server propagates the config option through a mutex-guarded setter since workspace/didChangeConfiguration can race with build-on-save workers.

Known limitations, left out deliberately: toggling the option only takes effect on the next build cycle (not added to the build-on-save restart set), workspace matching is byte-exact (case-insensitive filesystems can miss promotion — it fails open to the old behavior), and multi-root workspaces are scoped to each build's root. Deep comptime chains benefit from raising -freference-trace via build_on_save_args.

Tests cover: promotion with notes and sentinel entries, the disabled option, no-workspace-frame degradation, workspace-local errors staying put, innermost-frame selection with two user frames, null src_base_path, trace survival through version-merge (addBundleAsRoots), and the path predicate.

closes #3239
closes #2018

When a compile error is located outside of the workspace (e.g. inside the
standard library or a dependency), report the error at the innermost
reference trace location that is inside the workspace instead. The
original error location, the error notes and the remaining reference
trace entries are preserved as LSP related information.

Previously such errors were published under the library file's URI and
their reference traces were discarded entirely, which made them
effectively invisible in the editor.

The new `promote_reference_traces` config option (default: true) can be
used to restore the previous behavior.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

use reference trace to provide better build-on-save source locations for errors Reference-trace and note-chain presentation (trace promotion)

1 participant