ttsc 0.26.2 → 0.28.0

package/internal/graph/artifacts.go

@@ -0,0 +1,230 @@
+package graph
+
+import (
+  "encoding/json"
+  "os"
+  "sort"
+  "strings"
+)
+
+// Artifact is one thing a declaration's documentation can cite that is not a
+// TypeScript declaration — a document section, a data model field, an API
+// operation.
+//
+// It is the wire shape `@ttsc/lint`'s `graph-nodes` verb prints, restated here
+// rather than imported: `packages/lint` is its own Go module and deliberately
+// carries no requirement on this one, with its reason written in that manifest.
+// What binds the two is the JSON contract, so the keys below are the contract
+// and the Go field names are not — the same rule DumpNode already states.
+//
+// Nothing here is a judgement. The rule that materialized these decides what is
+// covered, what is a legitimate exclusion, and what is missing, and it delivers
+// those as compile errors. The graph reports; the linter judges.
+type Artifact struct {
+  Address  string   `json:"address"`
+  Kind     string   `json:"kind"`
+  Readable string   `json:"readable,omitempty"`
+  Parent   string   `json:"parent,omitempty"`
+  File     string   `json:"file,omitempty"`
+  Line     int      `json:"line,omitempty"`
+  Aliases  []string `json:"aliases,omitempty"`
+}
+
+// artifactNodeKinds maps a published artifact kind onto this graph's node kind.
+//
+// The vocabulary is closed on purpose. A kind the graph does not model is a node
+// a consumer would rank, contain, and display as something it is not, so it is
+// dropped rather than guessed at — and the capability claim is what tells a
+// consumer the producer looked at all.
+var artifactNodeKinds = map[string]NodeKind{
+  "markdown_document": NodeMarkdownDocument,
+  "markdown_section":  NodeMarkdownSection,
+  "prisma_model":      NodePrismaModel,
+  "prisma_column":     NodePrismaColumn,
+  "prisma_relation":   NodePrismaRelation,
+  "swagger_operation": NodeSwaggerOperation,
+}
+
+// IsArtifactKind reports whether a node kind names a published artifact rather
+// than a TypeScript declaration.
+//
+// It is what keeps an artifact out of the places that assume a declaration: an
+// id built from the `path#name:kind` grammar, and a tour seed. A document
+// section is neither the shape of a declaration nor an answer to "what is this
+// project and how does it run".
+func IsArtifactKind(kind NodeKind) bool {
+  for _, mapped := range artifactNodeKinds {
+    if mapped == kind {
+      return true
+    }
+  }
+  return false
+}
+
+// LoadArtifacts reads the artifact set a plugin published, or nil when no path
+// was given.
+//
+// A missing file is not an error: the caller names a path a plugin may or may
+// not have produced, and a project that publishes nothing is the common case. A
+// file that exists and does not parse is an error, because that is a producer
+// the caller was told to expect.
+func LoadArtifacts(path string) ([]Artifact, error) {
+  if strings.TrimSpace(path) == "" {
+    return nil, nil
+  }
+  data, err := os.ReadFile(path)
+  if err != nil {
+    if os.IsNotExist(err) {
+      return nil, nil
+    }
+    return nil, err
+  }
+  return ParseArtifacts(data)
+}
+
+// ParseArtifacts decodes a published set from the bytes it was read as.
+//
+// Split from LoadArtifacts for a caller that has to hash the same bytes it
+// parses. Reading the file twice — once to state what it holds and once to
+// decode it — lets an overwrite land between the two, leaving a session whose
+// recorded identity describes a set it is not holding.
+func ParseArtifacts(data []byte) ([]Artifact, error) {
+  var artifacts []Artifact
+  if err := json.Unmarshal(data, &artifacts); err != nil {
+    return nil, err
+  }
+  return artifacts, nil
+}
+
+// ApplyArtifacts adds the published artifacts to a built graph as nodes, records
+// each one's parent, and resolves every documentation tag whose target names one
+// into a doc-ref edge.
+//
+// The address is the node id verbatim. That is deliberate and has a real
+// benefit: the token an author wrote in a tag is the handle an agent submits
+// back. It also means these ids do not follow the `path#name:kind` grammar —
+// `prisma:Sale.price` carries no path because a Prisma model name is unique
+// across the schema folder, and `POST:/orders` has no file at all — which is why
+// a consumer parsing an id has to gate on the kind first.
+//
+// An address that collides with an existing node loses: a checker-resolved
+// declaration is a fact of this Program, and a published artifact is not.
+func ApplyArtifacts(g *Graph, artifacts []Artifact) {
+  if g == nil || len(artifacts) == 0 {
+    return
+  }
+  // Sorted so the emitted node and edge order is a function of the addresses
+  // rather than of the order a plugin happened to walk its documents.
+  sorted := make([]Artifact, len(artifacts))
+  copy(sorted, artifacts)
+  sort.SliceStable(sorted, func(i, j int) bool { return sorted[i].Address < sorted[j].Address })
+
+  // Every address an artifact answers to, including its aliases, so a citation
+  // written against either spelling resolves to the one node.
+  byAddress := map[string]string{}
+  for _, artifact := range sorted {
+    kind, known := artifactNodeKinds[artifact.Kind]
+    if !known || artifact.Address == "" {
+      continue
+    }
+    if _, exists := g.Nodes[artifact.Address]; exists {
+      continue
+    }
+    node := &Node{
+      ID:     artifact.Address,
+      Name:   artifact.Address,
+      Simple: artifact.Readable,
+      Kind:   kind,
+      File:   artifact.File,
+    }
+    if artifact.Line > 0 {
+      node.ArtifactLine = artifact.Line
+    }
+    g.Nodes[artifact.Address] = node
+    byAddress[artifact.Address] = artifact.Address
+  }
+
+  // Aliases are registered after every address, and only where nothing claims
+  // the spelling. An alias is an additional name for one artifact, never a
+  // rename of another: registering it in the same pass let one artifact's alias
+  // overwrite an earlier artifact's own address, and a citation of that address
+  // then resolved to the wrong node — a confident wrong answer, which is worse
+  // than the token it replaced.
+  for _, artifact := range sorted {
+    if _, published := g.Nodes[artifact.Address]; !published {
+      continue
+    }
+    for _, alias := range artifact.Aliases {
+      if alias == "" || alias == artifact.Address {
+        continue
+      }
+      if _, claimed := byAddress[alias]; claimed {
+        continue
+      }
+      byAddress[alias] = artifact.Address
+    }
+  }
+
+  // Containment rides the node rather than an edge, because `contains` is
+  // synthesized by the TypeScript memory layer for declarations and a second
+  // producer of the same relation would put two answers in the graph. A parent
+  // naming nothing published is cleared: the child is still a real artifact and
+  // sits at the top of its chain, and fabricating the parent is what must not
+  // happen.
+  for _, artifact := range sorted {
+    node, exists := g.Nodes[artifact.Address]
+    if !exists || artifact.Parent == "" {
+      continue
+    }
+    if parent, resolved := byAddress[artifact.Parent]; resolved && parent != artifact.Address {
+      node.ArtifactParent = parent
+    }
+  }
+
+  // A tag's target is its leading token, the same rule the reverse index uses.
+  // A tag naming nothing published resolves to nothing and stays what it always
+  // was: text on the node, for the linter to judge.
+  //
+  // The edges are appended with a dedup of their own rather than through
+  // addEdge. This runs after the build, and the build releases the scratch it no
+  // longer reads — `seen` among it — so the shared helper would write to a map
+  // that is deliberately nil. Two declarations citing one address are two edges;
+  // one declaration citing it twice, under two tag names, is one.
+  seen := map[edgeKey]struct{}{}
+  for _, edge := range g.Edges {
+    seen[edgeKey{from: edge.From, to: edge.To, kind: wireEdgeKind(edge.Kind, edge.Origin)}] = struct{}{}
+  }
+  for _, tag := range g.DocTags {
+    if tag == nil {
+      continue
+    }
+    target := leadingToken(tag.Text)
+    if target == "" {
+      continue
+    }
+    address, resolved := byAddress[target]
+    if !resolved {
+      continue
+    }
+    key := edgeKey{from: tag.Target, to: address, kind: wireEdgeKind(EdgeDocRef, "")}
+    if _, exists := seen[key]; exists {
+      continue
+    }
+    seen[key] = struct{}{}
+    g.Edges = append(g.Edges, &Edge{From: tag.Target, To: address, Kind: EdgeDocRef, Pos: -1, End: -1})
+  }
+}
+
+// leadingToken is the first whitespace-delimited word of a tag's text, which is
+// the address a citation names. Everything after it is prose the author wrote
+// for a human.
+func leadingToken(text string) string {
+  trimmed := strings.TrimSpace(text)
+  if trimmed == "" {
+    return ""
+  }
+  if space := strings.IndexAny(trimmed, " \t"); space >= 0 {
+    return trimmed[:space]
+  }
+  return trimmed
+}

package/internal/graph/artifacts_index_what_a_plugin_published_test.go

@@ -0,0 +1,154 @@
+package graph
+
+import (
+  "path/filepath"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestArtifactsIndexWhatAPluginPublished verifies that a published artifact
+// becomes a node a citation resolves to, and that nothing else does.
+//
+// The reverse question already worked without this: a lookup on an address
+// answered with the declarations citing it, keyed on the token. What it could
+// not answer is what the address names — the heading's own text, what sits under
+// it — and that is what a node adds. The edge is the same `doc-ref` a resolved
+// `{@link}` already produced; the difference is that it now has an other end.
+//
+// Every negative here is a way the index could lie. A fabricated node for an
+// address nobody published would answer a question with an invention; a parent
+// naming nothing would put an artifact under a container that does not exist;
+// and an unknown kind would be ranked and contained as something it is not.
+//
+//  1. Build a graph for a project whose declarations cite four addresses.
+//  2. Apply a published set covering three of them, one by an alias, one under
+//     a parent, plus an unpublishable entry.
+//  3. Assert the nodes, their containment, and the resolved edges — and that the
+//     uncited address, the unknown kind, and the dangling parent produced none.
+func TestArtifactsIndexWhatAPluginPublished(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
+  "files": ["src/main.ts"]
+}
+`)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), `/** @evidence docs/sale.md#pricing States the rule. */
+export function priced(): void {}
+
+/** @evidence prisma:Sale.price The column it reads. */
+export function column(): void {}
+
+/** @evidence docs/sale.md#alias Reached by its other name. */
+export function aliased(): void {}
+
+/** @evidence docs/sale.md#nobody-published-this Still just text. */
+export function unpublished(): void {}
+`)
+
+  prog, _, err := driver.LoadProgram(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil || prog == nil {
+    t.Fatalf("could not load the probe project: %v", err)
+  }
+  defer func() { _ = prog.Close() }()
+
+  g := Build(prog)
+  before := len(g.Nodes)
+  ApplyArtifacts(g, []Artifact{
+    {
+      Address:  "docs/sale.md",
+      Kind:     "markdown_document",
+      Readable: "Sale",
+      File:     "docs/sale.md",
+      Line:     1,
+    },
+    {
+      Address:  "docs/sale.md#pricing",
+      Kind:     "markdown_section",
+      Readable: "Pricing",
+      Parent:   "docs/sale.md",
+      File:     "docs/sale.md",
+      Line:     7,
+      Aliases:  []string{"docs/sale.md#alias"},
+    },
+    {
+      Address:  "prisma:Sale.price",
+      Kind:     "prisma_column",
+      Readable: "Prisma column 'Sale.price'",
+      Parent:   "prisma:Sale",
+      File:     "prisma/schema.prisma",
+      Line:     12,
+    },
+    {Address: "docs/sale.md#unknown", Kind: "not_a_kind"},
+    // Its alias is another artifact's own address. An alias is an additional
+    // name for one artifact, never a rename of another, so this must not move
+    // `docs/sale.md#pricing` onto this node — a citation of that address would
+    // then resolve to the wrong section, which is a confident wrong answer.
+    {
+      Address:  "docs/sale.md#shadow",
+      Kind:     "markdown_section",
+      Readable: "Shadow",
+      Aliases:  []string{"docs/sale.md#pricing"},
+      File:     "docs/sale.md",
+      Line:     20,
+    },
+  })
+
+  if got := len(g.Nodes) - before; got != 4 {
+    t.Fatalf("added %d nodes, want 4; an unknown kind must contribute none", got)
+  }
+  if _, fabricated := g.Nodes["docs/sale.md#nobody-published-this"]; fabricated {
+    t.Fatal("an address nobody published became a node; the tag text carries it and the linter judges it")
+  }
+  if _, fabricated := g.Nodes["prisma:Sale"]; fabricated {
+    t.Fatal("a parent nobody published became a node")
+  }
+
+  section := g.Nodes["docs/sale.md#pricing"]
+  if section == nil {
+    t.Fatal("the cited section is not a node")
+  }
+  if section.Simple != "Pricing" {
+    t.Fatalf("the section carries %q, not the heading text an index exists to hold", section.Simple)
+  }
+  if section.ArtifactLine != 7 {
+    t.Fatalf("the section starts at line %d, want 7", section.ArtifactLine)
+  }
+  if section.ArtifactParent != "docs/sale.md" {
+    t.Fatalf("the section's parent is %q, want its document", section.ArtifactParent)
+  }
+  if parent := g.Nodes["prisma:Sale.price"].ArtifactParent; parent != "" {
+    t.Fatalf("a parent naming no published node survived as %q; it must be cleared, not fabricated", parent)
+  }
+
+  cited := map[string]bool{}
+  for _, edge := range g.Edges {
+    if edge.Kind == EdgeDocRef {
+      cited[edge.To] = true
+    }
+  }
+  for _, address := range []string{"docs/sale.md#pricing", "prisma:Sale.price"} {
+    if !cited[address] {
+      t.Fatalf("no doc-ref edge resolved to %q", address)
+    }
+  }
+  if cited["docs/sale.md#alias"] {
+    t.Fatal("an alias became its own edge target; it has to resolve to the one node")
+  }
+  // The alias resolves to the same node, so the declaration citing it and the
+  // declaration citing the canonical address point at one artifact.
+  aliasEdges := 0
+  for _, edge := range g.Edges {
+    if edge.Kind == EdgeDocRef && edge.To == "docs/sale.md#pricing" {
+      aliasEdges++
+    }
+  }
+  if aliasEdges != 2 {
+    t.Fatalf("%d declarations resolved to the section, want 2 (its address and its alias)", aliasEdges)
+  }
+  for _, edge := range g.Edges {
+    if edge.Kind == EdgeDocRef && edge.To == "docs/sale.md#shadow" {
+      t.Fatal("an alias claimed another artifact's address; a citation resolved to the wrong node")
+    }
+  }
+}

package/internal/graph/artifacts_survive_a_partial_rebuild_test.go

@@ -0,0 +1,89 @@
+package graph
+
+import (
+  "path/filepath"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestArtifactsSurviveAPartialRebuild verifies that a citation of an artifact is
+// still a relation after the incremental path rebuilds the file that wrote it.
+//
+// A partial build re-resolves the outgoing facts of the files it selected, and a
+// citation is one of them. The full snapshot applied the published artifacts and
+// the incremental one did not, so editing a declaration that cites a document
+// section rebuilt it with that edge missing — the client's graph silently lost a
+// relation it had a moment earlier, and only a full reload brought it back.
+//
+// The nodes are re-added rather than assumed present because a partial starts
+// with only its selected files' nodes. They are the same nodes under the same
+// ids, which is why the store can replace like with like.
+//
+//  1. Build the complete graph with artifacts applied, and confirm the edge.
+//  2. Rebuild only the citing file, as the shard path does.
+//  3. Assert the edge is there again, and that the artifact came with it.
+func TestArtifactsSurviveAPartialRebuild(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
+  "files": ["src/main.ts"]
+}
+`)
+  source := filepath.Join(root, "src", "main.ts")
+  writeFile(t, source, `/** @evidence docs/sale.md#pricing States the rule. */
+export function priced(): void {}
+`)
+
+  prog, _, err := driver.LoadProgram(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil || prog == nil {
+    t.Fatalf("could not load the probe project: %v", err)
+  }
+  defer func() { _ = prog.Close() }()
+
+  published := []Artifact{
+    {
+      Address:  "docs/sale.md#pricing",
+      Kind:     "markdown_section",
+      Readable: "Pricing",
+      File:     "docs/sale.md",
+      Line:     7,
+    },
+  }
+
+  complete := Build(prog)
+  ApplyArtifacts(complete, published)
+  if !citesArtifact(complete) {
+    t.Fatal("the complete build did not resolve the citation")
+  }
+
+  var selected string
+  for _, node := range complete.Nodes {
+    if node.File != "" && node.Kind == NodeFunction {
+      selected = node.File
+      break
+    }
+  }
+  if selected == "" {
+    t.Fatal("the probe project produced no declaration to reselect")
+  }
+
+  partial := BuildFiles(prog, []string{selected}, complete.Nodes)
+  ApplyArtifacts(partial, published)
+  if !citesArtifact(partial) {
+    t.Fatal("the partial rebuild dropped the citation edge the full build had")
+  }
+  if _, published := partial.Nodes["docs/sale.md#pricing"]; !published {
+    t.Fatal("the partial rebuild resolved an edge to a node it did not carry")
+  }
+}
+
+// citesArtifact reports whether any doc-ref edge lands on the probe's artifact.
+func citesArtifact(g *Graph) bool {
+  for _, edge := range g.Edges {
+    if edge.Kind == EdgeDocRef && edge.To == "docs/sale.md#pricing" {
+      return true
+    }
+  }
+  return false
+}

package/internal/graph/build.go

@@ -55,9 +55,39 @@ func BuildFiles(prog *driver.Program, selected []string, baseNodes map[string]*N
     collectDeclarations(g, file)
   }
   g.addEdges(prog, selectedFiles, selected != nil)
+  g.releaseBuildState()
   return g
 }
 
+// releaseBuildState drops the scratch the build needed, once the edge pass has
+// finished with it.
+//
+// Every map cleared here is documented build-only, and each holds pointers into
+// the compiler AST or into the preceding generation”'s nodes: resolved is keyed
+// by *shimast.Node, docHosts holds one per documented declaration, and baseNodes
+// is the whole prior endpoint index. A consumer that retains the returned Graph
+// therefore pinned all of it for as long as it held the graph — and
+// internal/graphsymbols retains one for the lifetime of an editor session
+// between invalidations, closing the Program while the maps that reference its
+// AST live on. Clearing them here rather than at that consumer is what keeps the
+// decision with the producer, which is the only side that knows which fields are
+// scratch.
+//
+// ExportedTargets and ImplementationSources are deliberately not cleared: the
+// shard expansion path in cmd/ttscgraph/serve_shards.go reads both after this
+// returns, and Nodes/Edges/Decorators/DocTags are the graph itself.
+func (g *Graph) releaseBuildState() {
+  g.docTagPositions = nil
+  g.docHosts = nil
+  g.docHostPositions = nil
+  g.bodyNodes = nil
+  g.seen = nil
+  g.resolved = nil
+  g.edgeEvidenceFiles = nil
+  g.baseNodes = nil
+  g.selectedFiles = nil
+}
+
 // SourceTexts maps every program source to the resident checker text.
 // Declaration and virtual bundled files are included because external graph
 // leaves still carry facts and spans the source manifest must attest to.
@@ -454,6 +484,11 @@ func collectMembers(g *Graph, path string, statement *shimast.Node) {
 
 func putDeclaredNode(g *Graph, path, name string, kind NodeKind, declaration *shimast.Node) {
   id := nodeID(path, name, kind)
+  // Tags belong to the identity, not to whichever declaration of it wins the
+  // display span below. An overload run documented on its first signature and
+  // implemented underneath returns early from the node branch, so collecting
+  // there would drop exactly the declaration authors write documentation on.
+  collectDocTags(g, id, declaration)
   hasBody := declarationHasImplementation(declaration, kind)
   if _, exists := g.Nodes[id]; exists {
     if !hasBody || g.bodyNodes[id] {

package/internal/graph/build_releases_the_scratch_it_no_longer_reads_test.go

@@ -0,0 +1,118 @@
+package graph
+
+import (
+  "path/filepath"
+  "reflect"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestBuildReleasesTheScratchItNoLongerReads verifies that a returned Graph
+// carries only what a consumer reads, and still carries what the shard path
+// reads after the call.
+//
+// Every field asserted nil below is documented build-only and holds pointers
+// into the compiler AST or into the preceding generation's nodes. They used to
+// survive the build, so a consumer retaining the Graph pinned all of it —
+// internal/graphsymbols keeps one for the lifetime of an editor session between
+// invalidations, closing the Program while the maps referencing its AST live on.
+// Measured on this repository's own packages, holding the Graph after closing
+// the Program retained 38.1 MB for @ttsc/lint, 52.5 MB for ttsc, and 58.2 MB for
+// @ttsc/graph; releasing the scratch brings those to 3.7, 5.0, and 4.0 MB.
+//
+// The assertion is structural rather than a heap measurement on purpose: a
+// megabyte threshold is a flaky test, while "the producer stopped holding it" is
+// the invariant and is exact.
+//
+//  1. Build the complete graph for a one-file project.
+//  2. Assert every build-only field is released.
+//  3. Assert the two fields the shard expansion reads after the call, and the
+//     graph itself, are not.
+func TestBuildReleasesTheScratchItNoLongerReads(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
+  "files": ["src/main.ts"]
+}
+`)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), `/** @evidence docs/a.md#x Cited. */
+export interface ISale { id: string }
+export class Store implements ISale {
+  public id: string = "";
+  public save(): void { this.load() }
+  public load(): void {}
+}
+export function run(store: Store): void { store.save() }
+`)
+
+  prog, _, err := driver.LoadProgram(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil || prog == nil {
+    t.Fatalf("could not load the probe project: %v", err)
+  }
+  defer func() { _ = prog.Close() }()
+
+  g := Build(prog)
+  assertScratchReleased(t, g, "complete build")
+
+  // The partial build is not a second case of the same thing: `baseNodes` and
+  // `selectedFiles` are nil on arrival in a complete build, so a complete build
+  // alone cannot fail on them. `baseNodes` is the largest of the nine and the
+  // one #1243 flagged as the caution, because it is passed in rather than built.
+  var mainFile string
+  for _, node := range g.Nodes {
+    mainFile = node.File
+    break
+  }
+  if mainFile == "" {
+    t.Fatal("the probe project produced no node to select a file from")
+  }
+  partial := BuildFiles(prog, []string{mainFile}, g.Nodes)
+  assertScratchReleased(t, partial, "partial build")
+
+  // The negative twin. Clearing scratch must not clear what the shard expansion
+  // in cmd/ttscgraph/serve_shards.go reads after BuildFiles returns.
+  if g.ExportedTargets == nil {
+    t.Error("ExportedTargets was released, but the shard path reads it after the build")
+  }
+  if g.ImplementationSources == nil {
+    t.Error("ImplementationSources was released, but the shard path reads it after the build")
+  }
+  if len(g.Nodes) == 0 || len(g.Edges) == 0 || len(g.DocTags) == 0 {
+    t.Fatalf("the graph itself is empty: %d nodes, %d edges, %d tags",
+      len(g.Nodes), len(g.Edges), len(g.DocTags))
+  }
+}
+
+// assertScratchReleased requires every unexported reference field of a returned
+// Graph to be nil.
+//
+// It reflects rather than naming the fields, because a hand-written list has to
+// be edited by the same person who forgets to edit releaseBuildState — which is
+// exactly how docHosts arrived beside resolved. Unexported fields are readable
+// this way: reflect.Value.IsNil needs no exported access, only Interface does.
+//
+// Exported fields are skipped: Nodes, Edges, Decorators, and DocTags are the
+// graph, and ExportedTargets and ImplementationSources are read after the build.
+func assertScratchReleased(t *testing.T, g *Graph, label string) {
+  t.Helper()
+  value := reflect.ValueOf(g).Elem()
+  for index := 0; index < value.NumField(); index++ {
+    field := value.Type().Field(index)
+    if field.IsExported() {
+      continue
+    }
+    switch value.Field(index).Kind() {
+    case reflect.Map, reflect.Slice, reflect.Ptr:
+    default:
+      continue
+    }
+    if !value.Field(index).IsNil() {
+      t.Errorf(
+        "%s: %s survived; it pins the AST for as long as a consumer holds the graph",
+        label,
+        field.Name,
+      )
+    }
+  }
+}