Display tree of srcref/srcfile objects

[lionel-]

This PR:

• Documents what I've learned about source references while working on Ark in a single place.
• Implements a tree viewer for source reference objects.

The tree viewer is helpful to get a grasp of the complex web of objects created by the parser:

• "srcref" and "wholeSrcref" attributes
• "srcref" objects wrapped in a list or unwrapped
• Multiple classes of "srcfile"
• Multiple kinds of srcref-bearing objects

Principles of the tree view:

• To avoid repetition of "srcfile" objects (attached to every "srcref" object), these are given an identifier on first visit and referred to by id on subsequent visits.
• The node labels indicate how to extract the object (via body(), attr(), or [[).
• We recurse in a mostly generic way, looking for srcref-like things even where we don't expect them (e.g. srcref or wholeSrcref attributes on lists).
• parsed is only shown if different from location (due to a #line directive)

Here is an example of src() showing its own srcrefs tree:

> lobstr::src(lobstr::src)
<closure>
├─attr("srcref"): <srcref>
│ ├─location: 202:8 - 228:1
│ ├─parsed: 788:8 - 814:1
│ └─attr("srcfile"): <srcfilealias> @001
│   ├─filename: "/private/tmp/RtmpPNQes3/R.INSTAL..."
│   └─original: <srcfilecopy> @002
│     ├─Enc: "unknown"
│     ├─filename: "/Users/lionel/R/Library/4.5-aarc..."
│     ├─fixedNewlines: TRUE
│     ├─isFile: TRUE
│     ├─lines<chr [2,049]>: ".packageName...", "#line 1 "/pr...", "#' Find memo...", ...
│     ├─timestamp: "2025-11-17 16:08:54"
│     └─wd: "/private/tmp/RtmpPNQes3/R.INSTAL..."
└─body(): <{>
  ├─attr("srcref"): <list>
  │ ├─[[1]]: <srcref>
  │ │ ├─location: 207:3 - 207:3
  │ │ ├─parsed: 793:3 - 793:3
  │ │ └─attr("srcfile"): @001
  │ ├─[[2]]: <srcref>
  │ │ ├─location: 208:3 - 208:47
  │ │ ├─parsed: 794:3 - 794:47
  │ │ └─attr("srcfile"): @001
  │ ├─[[3]]: <srcref>
  │ │ ├─location: 209:3 - 209:30
  │ │ ├─parsed: 795:3 - 795:30
  │ │ └─attr("srcfile"): @001
  │ ├─[[4]]: <srcref>
  │ │ ├─location: 211:3 - 211:41
  │ │ ├─parsed: 797:3 - 797:41
  │ │ └─attr("srcfile"): @001
  │ ├─[[5]]: <srcref>
  │ │ ├─location: 212:3 - 214:3
  │ │ ├─parsed: 798:3 - 800:3
  │ │ └─attr("srcfile"): @001
  │ ├─[[6]]: <srcref>
  │ │ ├─location: 217:3 - 219:3
  │ │ ├─parsed: 803:3 - 805:3
  │ │ └─attr("srcfile"): @001
  │ └─[[7]]: <srcref>
  │   ├─location: 221:3 - 227:3
  │   ├─parsed: 807:3 - 813:3
  │   └─attr("srcfile"): @001
  ├─attr("srcfile"): @001
  ├─attr("wholeSrcref"): <srcref>
  │ ├─location: 1:0 - 228:1
  │ ├─parsed: 1:0 - 814:1
  │ └─attr("srcfile"): @001
  ├─[[5]][[3]]: <{>
  │ ├─attr("srcref"): <list>
  │ │ ├─[[1]]: <srcref>
  │ │ │ ├─location: 212:24 - 212:24
  │ │ │ ├─parsed: 798:24 - 798:24
  │ │ │ └─attr("srcfile"): @001
  │ │ └─[[2]]: <srcref>
  │ │   ├─location: 213:5 - 213:27
  │ │   ├─parsed: 799:5 - 799:27
  │ │   └─attr("srcfile"): @001
  │ ├─attr("srcfile"): @001
  │ └─attr("wholeSrcref"): <srcref>
  │   ├─location: 1:0 - 214:3
  │   ├─parsed: 1:0 - 800:3
  │   └─attr("srcfile"): @001
  └─[[6]][[3]]: <{>
    ├─attr("srcref"): <list>
    │ ├─[[1]]: <srcref>
    │ │ ├─location: 217:45 - 217:45
    │ │ ├─parsed: 803:45 - 803:45
    │ │ └─attr("srcfile"): @001
    │ └─[[2]]: <srcref>
    │   ├─location: 218:5 - 218:46
    │   ├─parsed: 804:5 - 804:46
    │   └─attr("srcfile"): @001
    ├─attr("srcfile"): @001
    └─attr("wholeSrcref"): <srcref>
      ├─location: 1:0 - 219:3
      ├─parsed: 1:0 - 805:3
      └─attr("srcfile"): @001

[DavisVaughan]

I didn't read the code too closely but I did read the docs closely and I really like having this all in one place!

[DavisVaughan]

Need newline?

[hadley]

I think this looks great and you should feel free to merge whenever. But I'm also happy to discuss more 😄

[hadley]

Would this be better as a snapshot transformer?

[hadley]

Why do you need to save to a file? Doesn't (eval(parse_with_srcref(code))) give you an object with srcref?

[hadley]

I think you can drop most of the docs here

[hadley]

Do you need the assignment here?

[hadley]

Can you explain why this works interactively:

f <- function() {
  x + 1 # comment
  {}
}
scrub_src(src(f))

But not

expect_snapshot({
f <- function() {
  x + 1 # comment
  {}
}
scrub_src(src(f))
})