feat(radls): structured docs in builtin hover + funcs doc infrastructure

Hover on a built-in function now shows:

  1. The signature, as before.
  2. A horizontal rule.
  3. The structured prose description from docs/funcs/<name>.md.
  4. The first rad example block.

When no doc file exists for a builtin, hover falls back to the
signature-only view that's been there all along. The migration is
incremental: this commit lands the infrastructure plus docs for
five high-value functions (print, len, range, abs, sort) to prove
the path end-to-end. Migrating the remaining ~60 builtins is
follow-up work that each just needs a new docs/funcs/<name>.md.

Source of truth: docs/funcs/

- README.md explains the model: one file per function, required
  sections (# title, ## Signature, ## Parameters, ## Examples,
  ## Category), optional sections (## Notes, ## See also). File
  stem must match the function name and parse as a Rad identifier;
  contributor notes (README, scratch files) are filtered out by
  the codegen.
- print.md, len.md, range.md, abs.md, sort.md as the starter set.

Embedded copy: rts/embedded_funcs/

- Go's //go:embed needs files inside the Go package, so the
  authoritative docs/funcs/ tree is mirrored to rts/embedded_funcs/.
  TestFuncDocsSourceMatchesEmbedded gates drift between the two
  until the proper codegen pipeline lands - the build-time copy is
  a temporary stand-in that keeps the architecture honest.

Runtime parser: rts/funcdocs.go + rts/funcdocs_loader.go

- ParseFuncDoc parses the structured shape. Lenient about blank
  lines; strict about required sections.
- FuncDoc struct: Name, Description, Signature, Parameters,
  Examples, Category, Notes, SeeAlso.
- GetFuncDoc(name) returns the parsed doc lazily; FuncDocNames()
  enumerates registered docs.

LSP integration: radls/analysis/hover.go

- formatIdentHover branches on rts.GetFuncDoc for SymBuiltin: if
  the doc exists, render signature + '---' + description + first
  example. Otherwise fall through to the old signature-only path.
- BuiltinShowsSignatureAndDocs snapshot in hover.snap locks the
  new shape for 'print'.

Tests:

- TestFuncDocsValid: every embedded doc parses cleanly.
- TestFuncDocsMatchRegisteredBuiltins: docs only exist for real
  builtins (catches typo'd file names).
- TestFuncDocsSignatureMatchesRegistered: the doc's signature line
  is identical to the registered builtin's signature - drift in
  either direction fails the test.
- TestFuncDocsSourceMatchesEmbedded: docs/funcs/ and
  rts/embedded_funcs/ stay byte-identical.

The reverse completeness test (every registered builtin has a doc)
is intentionally NOT in this commit - it would force a 60-builtin
migration into one PR. The check lands once the migration finishes.

Author: amterp

core/testing/funcdocs_test.go

@@ -0,0 +1,146 @@
+package testing
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/amterp/rad/rts"
+)
+
+// TestFuncDocsValid verifies every docs/funcs/*.md file in the
+// embedded set parses cleanly through ParseFuncDoc. Catches
+// authors landing a malformed doc that the hover layer would
+// silently drop.
+func TestFuncDocsValid(t *testing.T) {
+	names := rts.FuncDocNames()
+	if len(names) == 0 {
+		t.Skip("no embedded func docs yet")
+	}
+	for _, name := range names {
+		name := name
+		t.Run(name, func(t *testing.T) {
+			doc := rts.GetFuncDoc(name)
+			if doc == nil {
+				t.Fatalf("FuncDocNames listed %q but GetFuncDoc returned nil", name)
+			}
+			if doc.Name != name {
+				t.Errorf("name mismatch: stem=%q, doc.Name=%q", name, doc.Name)
+			}
+			if doc.Signature == "" {
+				t.Errorf("%s: empty signature", name)
+			}
+			if !strings.Contains(doc.Signature, name+"(") {
+				t.Errorf("%s: signature %q doesn't start with the function name",
+					name, doc.Signature)
+			}
+			if len(doc.Examples) == 0 {
+				t.Errorf("%s: no example code blocks", name)
+			}
+			if doc.Category == "" {
+				t.Errorf("%s: empty category", name)
+			}
+		})
+	}
+}
+
+// TestFuncDocsMatchRegisteredBuiltins verifies that every embedded
+// doc names a function the runtime actually registers. Catches the
+// reverse-drift case: a doc author renames the file to `say.md`
+// while the runtime still exposes `print`.
+//
+// Note: the opposite assertion - every registered builtin has a
+// doc - is intentionally NOT in this test yet. The doc migration
+// is incremental; gating CI on 100% coverage would block landing
+// any incremental work. The completeness assertion will land once
+// the migration finishes.
+func TestFuncDocsMatchRegisteredBuiltins(t *testing.T) {
+	for _, name := range rts.FuncDocNames() {
+		if _, ok := rts.FnSignaturesByName[name]; !ok {
+			t.Errorf("doc exists for %q but no such builtin is registered", name)
+		}
+	}
+}
+
+// TestFuncDocsSignatureMatchesRegistered verifies the signature
+// line in each doc matches the registered builtin's signature
+// byte-for-byte. Catches the case where a doc author updates the
+// signature in source without updating the doc (or vice versa).
+func TestFuncDocsSignatureMatchesRegistered(t *testing.T) {
+	for _, name := range rts.FuncDocNames() {
+		doc := rts.GetFuncDoc(name)
+		sig, ok := rts.FnSignaturesByName[name]
+		if !ok {
+			continue // covered by TestFuncDocsMatchRegisteredBuiltins
+		}
+		if doc.Signature != sig.Signature {
+			t.Errorf("%s: doc signature %q != registered %q",
+				name, doc.Signature, sig.Signature)
+		}
+	}
+}
+
+// TestFuncDocsSourceMatchesEmbedded verifies the source docs at
+// docs/funcs/ are in sync with the embedded copy in
+// rts/embedded_funcs/. The embedded files are the artefact the
+// runtime actually reads; the docs/funcs/ tree is the canonical
+// editable source. Manual sync today; codegen later.
+func TestFuncDocsSourceMatchesEmbedded(t *testing.T) {
+	sourceDir := "../../docs/funcs"
+	embeddedDir := "../../rts/embedded_funcs"
+	if _, err := os.Stat(sourceDir); os.IsNotExist(err) {
+		t.Skipf("source dir %s missing", sourceDir)
+	}
+	if _, err := os.Stat(embeddedDir); os.IsNotExist(err) {
+		t.Skipf("embedded dir %s missing", embeddedDir)
+	}
+
+	sources, err := collectDocSet(sourceDir)
+	if err != nil {
+		t.Fatalf("read source: %v", err)
+	}
+	embedded, err := collectDocSet(embeddedDir)
+	if err != nil {
+		t.Fatalf("read embedded: %v", err)
+	}
+
+	for name, content := range sources {
+		if name == "README.md" {
+			continue
+		}
+		emb, ok := embedded[name]
+		if !ok {
+			t.Errorf("%s exists in docs/funcs/ but not in rts/embedded_funcs/", name)
+			continue
+		}
+		if string(content) != string(emb) {
+			t.Errorf("%s differs between docs/funcs/ and rts/embedded_funcs/", name)
+		}
+	}
+	for name := range embedded {
+		if _, ok := sources[name]; !ok {
+			t.Errorf("%s exists in rts/embedded_funcs/ but not in docs/funcs/", name)
+		}
+	}
+}
+
+func collectDocSet(dir string) (map[string][]byte, error) {
+	out := make(map[string][]byte)
+	err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		base := filepath.Base(path)
+		if info.IsDir() || !strings.HasSuffix(base, ".md") {
+			return nil
+		}
+		content, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		out[base] = content
+		return nil
+	})
+	return out, err
+}

docs/funcs/README.md

@@ -0,0 +1,93 @@
+# `docs/funcs/`: source of truth for built-in function docs
+
+These markdown files are the canonical documentation for Rad's
+built-in functions. Each file describes exactly one function. Two
+downstream consumers read this directory at build time:
+
+1. `tools/gen-funcs-go/main.go` generates `rts/funcs_gen.go`, the
+   in-memory map the LSP hover layer reads from to show a function's
+   description alongside its signature.
+2. `tools/gen-funcs-page/main.go` regenerates
+   `docs-web/docs/reference/functions.md`, the public-facing
+   functions reference. The aggregate page stays a derived artifact -
+   editing it directly invites drift.
+
+Treat these `.md` files as the single source. Editing the generated
+artifacts directly is a one-way ticket to mismatched docs.
+
+## File naming
+
+One file per function, named `<fn>.md` where `<fn>` is the function's
+name in Rad source (`print.md`, `range.md`, `parse_int.md`). The
+codegen skips this `README.md` explicitly and any file whose stem
+doesn't match the identifier rule `[a-z_][a-z0-9_]*`, so contributor
+notes (`scratch.txt`, `2025-plan.md`) won't be picked up.
+
+Internal `_rad_*` builtins do not belong here. Add their docs in the
+`docs/funcs/internal/` subdirectory if they need any documentation
+at all - the codegen ignores that path so the public surface stays
+clean.
+
+## Required sections
+
+Every file must contain these sections in this order:
+
+```markdown
+# <fn>
+
+Short one-paragraph description.
+
+## Signature
+
+`<fn>(...) -> <return_type>`
+
+## Parameters
+
+- `param_name` (`type`): description
+
+## Examples
+
+\`\`\`rad
+example_code()
+\`\`\`
+
+## Category
+
+<one word>
+```
+
+`# <fn>` is the H1 title. The function name has to match the file
+stem - codegen rejects mismatches.
+
+`## Signature` holds exactly one line of inline-code: the function's
+signature in `signatures.go`'s syntax. The codegen parses this
+through the same signature parser as the registered fns, so a typo
+fails the doc test.
+
+`## Parameters` lists each positional / keyword parameter. Order
+matches the signature.
+
+`## Examples` holds one or more rad code blocks. The first block is
+what hover renders inline; later blocks appear in the public docs
+page.
+
+`## Category` is a single word the public docs use to group
+functions ("io", "strings", "lists", "math", "time", "random",
+"shell", "system").
+
+## Optional sections
+
+- `## Notes` - call out edge cases or related concepts.
+- `## See also` - link to related fns by name.
+
+## Tests
+
+`core/testing/funcs_codegen_test.go` validates the doc set on every
+test run:
+
+- Every `.md` parses cleanly into the structured shape above.
+- Every signature line parses through `signatures.go`'s parser.
+- Re-running both generators into tempdirs and diffing against the
+  committed outputs fails if either generator's output drifts.
+- (Eventual goal) Every registered builtin has a `.md`. While the
+  migration is in progress this is opt-in.

docs/funcs/abs.md

@@ -0,0 +1,29 @@
+# abs
+
+Returns the absolute value of a number. The result's type matches
+the input - `int` in, `int` out; `float` in, `float` out.
+
+## Signature
+
+`abs(_num: int|float) -> int|float`
+
+## Parameters
+
+- `_num` (`int|float`): the number to take the absolute value of.
+
+## Examples
+
+```rad
+abs(-5)        // -> 5
+abs(5)         // -> 5
+abs(-3.14)     // -> 3.14
+abs(0)         // -> 0
+```
+
+## Category
+
+math
+
+## See also
+
+`floor`, `ceil`, `round`

docs/funcs/len.md

@@ -0,0 +1,30 @@
+# len
+
+Returns the number of elements in a string, list, or map. For
+strings this is the rune count (not byte count), so unicode characters
+contribute one each.
+
+## Signature
+
+`len(_val: str|list|map) -> int`
+
+## Parameters
+
+- `_val` (`str|list|map`): the collection to measure.
+
+## Examples
+
+```rad
+len("hello")              // -> 5
+len([1, 2, 3])            // -> 3
+len({"a": 1, "b": 2})     // -> 2
+len("héllo")              // -> 5 (rune count, not byte count)
+```
+
+## Category
+
+lists
+
+## See also
+
+`sort`, `keys`, `values`

docs/funcs/print.md

@@ -0,0 +1,34 @@
+# print
+
+Writes its arguments to stdout, separated by a space, followed by a
+newline. The default workhorse for output. For error output, use
+`print_err`; for structured pretty-printing, use `pprint`.
+
+## Signature
+
+`print(*_items: any, *, sep: str = " ", end: str = "\n") -> void`
+
+## Parameters
+
+- `_items` (variadic `any`): values to print. Each is converted to
+  its string form via the default formatter.
+- `sep` (`str`, keyword-only, default `" "`): separator inserted
+  between consecutive items.
+- `end` (`str`, keyword-only, default `"\n"`): trailing text after
+  the last item. Set to `""` to print without a newline.
+
+## Examples
+
+```rad
+print("hello", "world")    // -> hello world
+print(1, 2, 3, sep=", ")   // -> 1, 2, 3
+print("no newline", end="") // -> no newline
+```
+
+## Category
+
+io
+
+## See also
+
+`print_err`, `pprint`, `debug`

docs/funcs/range.md

@@ -0,0 +1,38 @@
+# range
+
+Returns a list of numbers covering the half-open interval
+`[start, stop)`. With one argument, `start` defaults to 0. The list
+type matches the inputs - all ints produces an `int[]`, any float
+produces a `float[]`.
+
+## Signature
+
+`range(_arg1: float|int, _arg2: (float|int)?, _step: float|int = 1) -> float[]|int[]`
+
+## Parameters
+
+- `_arg1` (`float|int`): when `_arg2` is null, this is the upper
+  bound `stop` and `start` is implicitly 0. When `_arg2` is set,
+  this is the `start`.
+- `_arg2` (optional `float|int`): the upper bound `stop`. The
+  returned list never includes this value.
+- `_step` (`float|int`, default `1`): the spacing between
+  successive values. Must be non-zero; negative steps count down
+  when `start > stop`.
+
+## Examples
+
+```rad
+range(5)              // -> [0, 1, 2, 3, 4]
+range(1, 5)           // -> [1, 2, 3, 4]
+range(0, 1, 0.25)     // -> [0.0, 0.25, 0.5, 0.75]
+range(10, 0, -2)      // -> [10, 8, 6, 4, 2]
+```
+
+## Category
+
+math
+
+## See also
+
+`for`, `len`