Skip to content

compiler: rustc-style diagnostic blocks for humans (1-line when piped) (2/2) - #2

Open
simonzeiger wants to merge 1 commit into
feat/site-diagnosticsfrom
feat/pretty-diagnostics
Open

simonzeiger wants to merge 1 commit into
feat/site-diagnosticsfrom
feat/pretty-diagnostics

Conversation

@simonzeiger

Copy link
Copy Markdown
Owner

Stack: 1/2: #1 · 2/2 (compiler/, tooling/, README.md, guide/)

Summary

Part 2 of #1: implements the rustc-style diagnostic formatter in compiler/src/format.rs for interactive terminals, Vite, and rx-tsc --pretty, while keeping piped CLI output to one plain line per error so agents and test harnesses pay zero extra tokens.

Why this approach

  1. TTY-gated CLI, no extra tokens when piped:
    rxc (stderr().is_terminal()) and rx-tsc (stdout.isTTY) only print source-annotated blocks and docs[CODE] links on interactive terminals (or with --pretty / RX_PRETTY=1; Vite renders blocks by default for terminal and overlay errors). When piped to an agent, CI, or eval/harness/* (or with --compact / RX_COMPACT=1), output stays a single plain line per error with no ANSI escapes or footer.
  2. Punctuation-driven split so ref/ stays untouched:
    Changing Diagnostic strings in check.rs would break byte-for-byte parity with ref/crate.ts, while per-code lookup tables would go stale as wording changes. Instead, check.rs and parse.rs messages are unchanged: split_message strips raw near '…' parser slices and splits on top-level punctuation ({head} — {tail}, keeping paired — … — asides intact in head, bulleting = help: on ", or " / option lists, separating causal/trailing notes into = note:, and handling {head}: {a; …; or b} lists like HELD_WRITE), ignoring delimiters inside `…`, "…", (...), {…}, or <Tag>.
  3. Formatting lives in compiler/ only:
    Since ref/ is the spec reference rather than the shipped CLI, formatting lives once in compiler/src/format.rs. serve.rs exposes { head, help, notes } on JSON diagnostics (used by rx-language-server) and pre-rendered rendered text on serve::analyze and app::app (used by rx-tsc and compiler/vite.mjs), and compiler/tests/format.rs checks that the 5 <pre class="err"> blocks in site/index.html stay in sync with format_diagnostic.

Extending to new diagnostics

  • New error codes and spec chapters work automatically: Any code added in check.rs or parse.rs gets error[CODE] (rule), --> file:line:col, UTF-16/tab/wide-char-aligned ^^^ carets, inline `code` and dimmed (RULE-n) styling on color TTYs and site/index.html, and its #code link into guide/diagnostics.md (verified across all 44 single-file rx before examples plus multi-module cases in tests/format.rs).
  • Punctuation drives = help: and = note:: Messages using " — " (with ", or " or ; ) or ": " + "; …; or …" split into = help: bullets automatically, causal/trailing notes render as = note:, and messages without a hint clause (WRITE_TO_NON_SOURCE) render as headline + caret with no empty = help: line.
  • Ready for expression-level spans: DiagnosticView accepts optional (start_col, end_col) UTF-16 columns, so narrowing checker ranges from whole-line to expression-level later will tighten carets across rxc, Vite, rx-tsc, and site/index.html without formatter changes.

CLI Output (rxc check)

Piped / agent default (or --compact):

like.rx:13:3: error UNHANDLED_FAILURE [R-f-5] a reader of likes (in <Like>) can fail with Error and no catch or errored boundary above it discharges Error — wrap it in `errored fallback(e) { … } { … }`, or catch it: `… catch (e) => …`

Interactive terminal (or --pretty):

error[UNHANDLED_FAILURE] (R-f-5): a reader of likes (in <Like>) can fail with Error and no
    catch or errored boundary above it discharges Error
  --> like.rx:13:3
13 |   <button onClick={() => { send() }}>♥ {likes}</button>
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   = help: • wrap it in `errored fallback(e) { … } { … }`
           • or catch it: `… catch (e) => …`

docs[UNHANDLED_FAILURE]: https://github.com/solidjs/reactivescript/blob/main/guide/diagnostics.md#unhandled_failure

Verification

  • cargo test --manifest-path compiler/Cargo.toml (unit tests + diagnostics_page.rs + tests/format.rs across all 44 single-file rx before examples, multi-module server/client diagnostics, and all 5 site/index.html blocks)
  • node --experimental-strip-types ref/crate.ts (364/364 conformance)
  • node --experimental-strip-types ref/run.ts

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.

1 participant