ux(radls, check): contextual rename errors + did-you-mean grammar

amterp · amterp · commit 552f59dc1f68 · 2026-05-28T20:29:13.000-05:00
+ hover stutter

Three small UX fixes that all touch user-facing strings.

Contextual rename errors

Previously the rename handler returned three generic sentinels:
"not a valid Rad identifier", "name is already in scope", "the
symbol under the cursor cannot be renamed". The user got no
hint about which rule they broke. Now wrapped with the specific
reason:

  - "not a valid Rad identifier: 1bad (identifiers can't start
    with a digit)"
  - "not a valid Rad identifier: if (this is a reserved Rad
    keyword)"
  - "name is already in scope: 'y' is already declared in this
    scope"
  - "name is already in scope: 'print' is already a built-in
    function"

The sentinels stay exported and the wrapped errors still match
via errors.Is, so anything keying off the existing constants
keeps working.

isValidRadIdentifier became validateRadIdentifier and returns a
reason string on rejection. scopeHasName became scopeCollision
and returns "declared in this scope" / "declared in an enclosing
scope" / "" so the caller can build a more precise message.

Did-you-mean Oxford-or grammar

The old format was "did you mean one of 'X', 'Y'?" which reads
awkwardly with two items (English says "X or Y" with two) and
clunkily with three (no Oxford-or separator). New format mirrors
rustc:

  - 1: "did you mean 'X'?"             (unchanged)
  - 2: "did you mean 'X' or 'Y'?"
  - 3+ Oxford-or: "did you mean 'X', 'Y', or 'Z'?"

emitUndefinedIdentifier in rts/check/binder.go now delegates the
formatting to formatDidYouMean in suggestion.go. The radls code-
action parser (extractDidYouMeanNames) was rewritten to pull
single-quoted runs out of the message regardless of which
separator shape was used - one parser handles all three cases
and survives future grammar tweaks.

Hover stutter for builtins

formatIdentHover (and the decl-site fallback formatSymbolHover)
were rendering builtins as "print: print(*_items: any) -&gt; void"
- a leading "name:" prefix that duplicates the signature's own
function name. The prefix is useful for locals (`(local) x:
int`) but pure noise for builtins. Now renders the signature
alone, matching rust-analyzer's convention.

Snapshots updated for: hover.snap BuiltinShowsSignatureAndDocs;
rename.snap RenameToInvalidIdentifier / RenameToCollidingName /
new reserved-keyword + unloaded-builtin cases; check.snap
suggestion lines; core/testing/check_test.go inline expected
strings.
diff --git a/core/testing/check_test.go b/core/testing/check_test.go
@@ -29,14 +29,14 @@ L1:11: ERROR
      1 | hello = 2 a
        |           ^ Undefined identifier 'a'
        |           (code: RAD20028)
-       = help: did you mean one of 'abs', 'map', 'max'?
+       = help: did you mean 'abs', 'map', or 'max'?
 
 L3:6: ERROR
 
      3 | 	yes no
        |      ^ Undefined identifier 'no'
        |      (code: RAD20028)
-       = help: did you mean one of 'now', 'int', 'pow'?
+       = help: did you mean 'now', 'int', or 'pow'?
 
 Reported 4 diagnostics.
 `
@@ -52,14 +52,14 @@ func Test_Check_UnknownFunctions(t *testing.T) {
      1 | foo()
        | ^ Undefined identifier 'foo'
        | (code: RAD20028)
-       = help: did you mean one of 'floor', 'now', 'pow'?
+       = help: did you mean 'floor', 'now', or 'pow'?
 
 L3:1: ERROR
 
      3 | qux()
        | ^ Undefined identifier 'qux'
        | (code: RAD20028)
-       = help: did you mean one of 'max', 'sum'?
+       = help: did you mean 'max' or 'sum'?
 
 Reported 2 diagnostics.
 `
diff --git a/core/testing/snapshots/control_flow/catch.snap b/core/testing/snapshots/control_flow/catch.snap
@@ -356,7 +356,7 @@ error[RAD20028]: Undefined identifier 'out'
 6 |   return error(out)
   |                ^^^
   |
-   = help: did you mean one of 'count', 'int', 'sort'?
+   = help: did you mean 'count', 'int', or 'sort'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/control_flow/defer.snap b/core/testing/snapshots/control_flow/defer.snap
@@ -72,7 +72,7 @@ error[RAD20028]: Undefined identifier 'asd'
 4 | print(asd)
   |       ^^^
   |
-   = help: did you mean one of 'abs', 'hash', 'rand'?
+   = help: did you mean 'abs', 'hash', or 'rand'?
    = info: rad explain RAD20028
 
 
@@ -96,7 +96,7 @@ error[RAD20028]: Undefined identifier 'asd'
 4 | defer print("bye2")
 5 | print("hi")
   |
-   = help: did you mean one of 'abs', 'hash', 'rand'?
+   = help: did you mean 'abs', 'hash', or 'rand'?
    = info: rad explain RAD20028
 
 
@@ -121,7 +121,7 @@ error[RAD20028]: Undefined identifier 'asd'
 4 | defer exit(3)  // this one executed before 'asd' error, so we should use its code
 5 | defer print("bye2")
   |
-   = help: did you mean one of 'abs', 'hash', 'rand'?
+   = help: did you mean 'abs', 'hash', or 'rand'?
    = info: rad explain RAD20028
 
 
@@ -146,7 +146,7 @@ error[RAD20028]: Undefined identifier 'asd'
 5 | defer print("bye2")
 6 | print("hi")
   |
-   = help: did you mean one of 'abs', 'hash', 'rand'?
+   = help: did you mean 'abs', 'hash', or 'rand'?
    = info: rad explain RAD20028
 
 
@@ -171,7 +171,7 @@ error[RAD20028]: Undefined identifier 'asd'
 4 | defer exit(0)  // this is a clean exit, so we should use the error from 'asd'
 5 | defer print("bye2")
   |
-   = help: did you mean one of 'abs', 'hash', 'rand'?
+   = help: did you mean 'abs', 'hash', or 'rand'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/functions/fn.snap b/core/testing/snapshots/functions/fn.snap
@@ -42,7 +42,7 @@ error[RAD20028]: Undefined identifier 'a'
 3 | a = 2
 4 | foo(10).print()
   |
-   = help: did you mean one of 'b', 'abs', 'map'?
+   = help: did you mean 'b', 'abs', or 'map'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/functions/fn_named.snap b/core/testing/snapshots/functions/fn_named.snap
@@ -49,7 +49,7 @@ error[RAD20028]: Undefined identifier 'add'
 4 | 	fn add(x, y):
 5 | 		return x + y
   |
-   = help: did you mean one of 'abs', 'rand', 'red'?
+   = help: did you mean 'abs', 'rand', or 'red'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/misc/interpolation.snap b/core/testing/snapshots/misc/interpolation.snap
@@ -65,7 +65,7 @@ error[RAD20028]: Undefined identifier 'var'
 2 | print("hello, {var}")
   |                ^^^
   |
-   = help: did you mean one of 'map', 'max', 'str'?
+   = help: did you mean 'map', 'max', or 'str'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/misc/migration.snap b/core/testing/snapshots/misc/migration.snap
@@ -75,7 +75,7 @@ error[RAD20028]: Undefined identifier 'get_default'
 3 | get_default(m, "b", 0)
   | ^^^^^^^^^^^
   |
-   = help: did you mean one of 'get_args', 'get_env', 'get_path'?
+   = help: did you mean 'get_args', 'get_env', or 'get_path'?
    = info: rad explain RAD20028
 
 
@@ -94,7 +94,7 @@ error[RAD20028]: Undefined identifier 'get_stash_dir'
 2 | get_stash_dir()
   | ^^^^^^^^^^^^^
   |
-   = help: did you mean one of 'get_stash_path', 'get_path', 'load_stash_file'?
+   = help: did you mean 'get_stash_path', 'get_path', or 'load_stash_file'?
    = info: rad explain RAD20028
 
 
@@ -114,7 +114,7 @@ error[RAD20028]: Undefined identifier 'get_default'
 3 | m.get_default("b", 0)
   |   ^^^^^^^^^^^
   |
-   = help: did you mean one of 'get_args', 'get_env', 'get_path'?
+   = help: did you mean 'get_args', 'get_env', or 'get_path'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/misc/misc.snap b/core/testing/snapshots/misc/misc.snap
@@ -512,7 +512,7 @@ error[RAD20028]: Undefined identifier 'usernme'
 4 | print(usernme)
   |       ^^^^^^^
   |
-   = help: did you mean one of 'username', 'user_name'?
+   = help: did you mean 'username' or 'user_name'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/misc/scoping.snap b/core/testing/snapshots/misc/scoping.snap
@@ -90,7 +90,7 @@ error[RAD20028]: Undefined identifier 'i'
 6 | print("i", i)
   |            ^
   |
-   = help: did you mean one of 'dim', 'int', 'min'?
+   = help: did you mean 'dim', 'int', or 'min'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/types/str_lexing.snap b/core/testing/snapshots/types/str_lexing.snap
@@ -475,7 +475,7 @@ error[RAD20028]: Undefined identifier 'text'
 5 | print(text)
   |       ^^^^
   |
-   = help: did you mean one of 'exit', 'ceil', 'int'?
+   = help: did you mean 'exit', 'ceil', or 'int'?
    = info: rad explain RAD20028
 
 
diff --git a/core/testing/snapshots/types/typing.snap b/core/testing/snapshots/types/typing.snap
@@ -228,7 +228,7 @@ error[RAD20028]: Undefined identifier 'x'
 3 | 	return x / y
   |         ^
   |
-   = help: did you mean one of '_x', '_y', 'max'?
+   = help: did you mean '_x', '_y', or 'max'?
    = info: rad explain RAD20028
 
 error[RAD20028]: Undefined identifier 'y'
@@ -238,7 +238,7 @@ error[RAD20028]: Undefined identifier 'y'
 3 | 	return x / y
   |             ^
   |
-   = help: did you mean one of '_y', '_x'?
+   = help: did you mean '_y' or '_x'?
    = info: rad explain RAD20028
 
 error[RAD30006]: Argument '_x' cannot be passed as named arg, only positionally
diff --git a/radls/analysis/code_actions.go b/radls/analysis/code_actions.go
@@ -101,33 +101,40 @@ func structuredFixFor(snap *DocumentVersion, d check.Diagnostic) (lsp.CodeAction
 // the suggestion string is the only carrier today and adding a
 // new field cascades through every BindIssue producer. Cheap
 // enough to do here at action-build time.
+//
+// Patterns we emit (must mirror formatDidYouMean in rts/check):
+//
+//	"did you mean 'X'?"                         -> 1 candidate
+//	"did you mean 'X' or 'Y'?"                  -> 2 candidates
+//	"did you mean 'X', 'Y', or 'Z'?"            -> 3+ Oxford-or
 func extractDidYouMeanNames(suggestion string) []string {
-	// Patterns we emit:
-	//   "did you mean 'X'?"
-	//   "did you mean one of 'X', 'Y', 'Z'?"
-	const prefix1 = "did you mean '"
-	const prefixN = "did you mean one of '"
-	if strings.HasPrefix(suggestion, prefix1) && !strings.HasPrefix(suggestion, prefixN) {
-		s := strings.TrimPrefix(suggestion, prefix1)
-		s = strings.TrimSuffix(s, "'?")
-		if s == "" {
-			return nil
-		}
-		return []string{s}
+	const prefix = "did you mean "
+	if !strings.HasPrefix(suggestion, prefix) {
+		return nil
 	}
-	if strings.HasPrefix(suggestion, prefixN) {
-		s := strings.TrimPrefix(suggestion, prefixN)
-		s = strings.TrimSuffix(s, "'?")
-		parts := strings.Split(s, "', '")
-		out := make([]string, 0, len(parts))
-		for _, p := range parts {
-			if p != "" {
-				out = append(out, p)
-			}
+	body := strings.TrimPrefix(suggestion, prefix)
+	body = strings.TrimSuffix(body, "?")
+	// Every name in the message is single-quoted; just pull out
+	// the quoted runs. Robust against the punctuation variations
+	// between the 1 / 2 / 3+ cases without needing to branch.
+	var out []string
+	for {
+		start := strings.Index(body, "'")
+		if start < 0 {
+			break
+		}
+		body = body[start+1:]
+		end := strings.Index(body, "'")
+		if end < 0 {
+			break
+		}
+		name := body[:end]
+		if name != "" {
+			out = append(out, name)
 		}
-		return out
+		body = body[end+1:]
 	}
-	return nil
+	return out
 }
 
 // buildNullUnionFix turns the tree-sitter ERROR span that covers
diff --git a/radls/analysis/hover.go b/radls/analysis/hover.go
@@ -77,7 +77,8 @@ func formatSymbolHover(sym *check.Symbol, info *check.TypeInfo) string {
 	}
 	typeStr := symbolTypeString(sym, info)
 	if sym.Kind == check.SymBuiltin {
-		return fmt.Sprintf("```rad\n%s: %s\n```", sym.Name, typeStr)
+		// Same no-stutter rule as formatIdentHover above.
+		return fmt.Sprintf("```rad\n%s\n```", typeStr)
 	}
 	kindLabel := symbolKindLabel(sym.Kind)
 	return fmt.Sprintf("```rad\n(%s) %s: %s\n```", kindLabel, sym.Name, typeStr)
@@ -122,16 +123,17 @@ func formatIdentHover(ident *rl.Identifier, resolved *check.Resolved, info *chec
 
 	typeStr := symbolTypeString(sym, info)
 	if sym.Kind == check.SymBuiltin {
-		// Signature is self-describing; the kind tag would
-		// just repeat what `name(args) -> ret` already says.
-		// When a structured doc exists for the builtin (an entry
-		// in docs/funcs/), append the description + first
-		// example so hover gives users prose context, not just
-		// the type. Falls back to signature-only when no doc.
+		// Builtin signature already leads with the function name
+		// (e.g. `print(*_items: any) -> void`), so prefixing with
+		// `print: ` would stutter the name. Render the signature
+		// alone, matching the rust-analyzer pattern for builtins.
+		// When a structured doc exists in docs/funcs/, append the
+		// description + first example so hover gives users prose
+		// context, not just the type.
 		if doc := rts.GetFuncDoc(sym.Name); doc != nil {
-			return renderBuiltinHoverWithDoc(sym.Name, typeStr, doc)
+			return renderBuiltinHoverWithDoc(typeStr, doc)
 		}
-		return fmt.Sprintf("```rad\n%s: %s\n```", sym.Name, typeStr)
+		return fmt.Sprintf("```rad\n%s\n```", typeStr)
 	}
 	kindLabel := symbolKindLabel(sym.Kind)
 	return fmt.Sprintf("```rad\n(%s) %s: %s\n```", kindLabel, sym.Name, typeStr)
@@ -140,10 +142,12 @@ func formatIdentHover(ident *rl.Identifier, resolved *check.Resolved, info *chec
 // renderBuiltinHoverWithDoc formats a builtin hover with structured
 // documentation - signature on top, description in the middle,
 // first example at the bottom. Markdown sections separated by `---`
-// so the LSP client renders them as visually distinct.
-func renderBuiltinHoverWithDoc(name, signature string, doc *rts.FuncDoc) string {
+// so the LSP client renders them as visually distinct. The
+// signature already includes the function name (e.g.
+// `print(*_items: any) -> void`), so no separate name label.
+func renderBuiltinHoverWithDoc(signature string, doc *rts.FuncDoc) string {
 	var b strings.Builder
-	fmt.Fprintf(&b, "```rad\n%s: %s\n```", name, signature)
+	fmt.Fprintf(&b, "```rad\n%s\n```", signature)
 	if doc.Description != "" {
 		b.WriteString("\n\n---\n\n")
 		b.WriteString(doc.Description)
diff --git a/radls/analysis/rename.go b/radls/analysis/rename.go
diff --git a/radls/lstesting/snapshots/hover.snap b/radls/lstesting/snapshots/hover.snap
diff --git a/radls/lstesting/snapshots/rename.snap b/radls/lstesting/snapshots/rename.snap
diff --git a/rts/check/binder.go b/rts/check/binder.go
diff --git a/rts/check/snapshots/parser_errors/invested_codes.snap b/rts/check/snapshots/parser_errors/invested_codes.snap
diff --git a/rts/check/suggestion.go b/rts/check/suggestion.go

Original file line number	Diff line number	Diff line change
`@@ -356,7 +356,7 @@ error[RAD20028]: Undefined identifier 'out'`
`356`	`356`	`6 \| return error(out)`
`357`	`357`	`\| ^^^`
`358`	`358`	`\|`
`359`		`- = help: did you mean one of 'count', 'int', 'sort'?`
	`359`	`+ = help: did you mean 'count', 'int', or 'sort'?`
`360`	`360`	`= info: rad explain RAD20028`
`361`	`361`
`362`	`362`
Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ error[RAD20028]: Undefined identifier 'a'`
`42`	`42`	`3 \| a = 2`
`43`	`43`	`4 \| foo(10).print()`
`44`	`44`	`\|`
`45`		`- = help: did you mean one of 'b', 'abs', 'map'?`
	`45`	`+ = help: did you mean 'b', 'abs', or 'map'?`
`46`	`46`	`= info: rad explain RAD20028`
`47`	`47`
`48`	`48`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ error[RAD20028]: Undefined identifier 'add'`
`49`	`49`	`4 \| fn add(x, y):`
`50`	`50`	`5 \| return x + y`
`51`	`51`	`\|`
`52`		`- = help: did you mean one of 'abs', 'rand', 'red'?`
	`52`	`+ = help: did you mean 'abs', 'rand', or 'red'?`
`53`	`53`	`= info: rad explain RAD20028`
`54`	`54`
`55`	`55`
Original file line number	Diff line number	Diff line change
`@@ -65,7 +65,7 @@ error[RAD20028]: Undefined identifier 'var'`
`65`	`65`	`2 \| print("hello, {var}")`
`66`	`66`	`\| ^^^`
`67`	`67`	`\|`
`68`		`- = help: did you mean one of 'map', 'max', 'str'?`
	`68`	`+ = help: did you mean 'map', 'max', or 'str'?`
`69`	`69`	`= info: rad explain RAD20028`
`70`	`70`
`71`	`71`
Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ error[RAD20028]: Undefined identifier 'get_default'`
`75`	`75`	`3 \| get_default(m, "b", 0)`
`76`	`76`	`\| ^^^^^^^^^^^`
`77`	`77`	`\|`
`78`		`- = help: did you mean one of 'get_args', 'get_env', 'get_path'?`
	`78`	`+ = help: did you mean 'get_args', 'get_env', or 'get_path'?`
`79`	`79`	`= info: rad explain RAD20028`
`80`	`80`
`81`	`81`
`@@ -94,7 +94,7 @@ error[RAD20028]: Undefined identifier 'get_stash_dir'`
`94`	`94`	`2 \| get_stash_dir()`
`95`	`95`	`\| ^^^^^^^^^^^^^`
`96`	`96`	`\|`
`97`		`- = help: did you mean one of 'get_stash_path', 'get_path', 'load_stash_file'?`
	`97`	`+ = help: did you mean 'get_stash_path', 'get_path', or 'load_stash_file'?`
`98`	`98`	`= info: rad explain RAD20028`
`99`	`99`
`100`	`100`
`@@ -114,7 +114,7 @@ error[RAD20028]: Undefined identifier 'get_default'`
`114`	`114`	`3 \| m.get_default("b", 0)`
`115`	`115`	`\| ^^^^^^^^^^^`
`116`	`116`	`\|`
`117`		`- = help: did you mean one of 'get_args', 'get_env', 'get_path'?`
	`117`	`+ = help: did you mean 'get_args', 'get_env', or 'get_path'?`
`118`	`118`	`= info: rad explain RAD20028`
`119`	`119`
`120`	`120`
Original file line number	Diff line number	Diff line change
`@@ -512,7 +512,7 @@ error[RAD20028]: Undefined identifier 'usernme'`
`512`	`512`	`4 \| print(usernme)`
`513`	`513`	`\| ^^^^^^^`
`514`	`514`	`\|`
`515`		`- = help: did you mean one of 'username', 'user_name'?`
	`515`	`+ = help: did you mean 'username' or 'user_name'?`
`516`	`516`	`= info: rad explain RAD20028`
`517`	`517`
`518`	`518`
Original file line number	Diff line number	Diff line change
`@@ -90,7 +90,7 @@ error[RAD20028]: Undefined identifier 'i'`
`90`	`90`	`6 \| print("i", i)`
`91`	`91`	`\| ^`
`92`	`92`	`\|`
`93`		`- = help: did you mean one of 'dim', 'int', 'min'?`
	`93`	`+ = help: did you mean 'dim', 'int', or 'min'?`
`94`	`94`	`= info: rad explain RAD20028`
`95`	`95`
`96`	`96`
Original file line number	Diff line number	Diff line change
`@@ -475,7 +475,7 @@ error[RAD20028]: Undefined identifier 'text'`
`475`	`475`	`5 \| print(text)`
`476`	`476`	`\| ^^^^`
`477`	`477`	`\|`
`478`		`- = help: did you mean one of 'exit', 'ceil', 'int'?`
	`478`	`+ = help: did you mean 'exit', 'ceil', or 'int'?`
`479`	`479`	`= info: rad explain RAD20028`
`480`	`480`
`481`	`481`