ttsc 0.26.2 → 0.28.0

package/internal/graph/doc_tags_capture_every_unrecognized_tag_test.go

@@ -0,0 +1,165 @@
+package graph
+
+import (
+  "path/filepath"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestDocTagsCaptureEveryUnrecognizedTag verifies that the build pass records a
+// DocTag for each documentation tag TypeScript does not recognize, on every
+// declaration form, and records nothing for the tags it does.
+//
+// The population boundary is the whole design: naming particular tags would make
+// the compiler host know one convention, so the pass collects exactly what the
+// parser could not interpret. That makes the known-tag half of this test
+// load-bearing rather than incidental — if `@param` ever arrived here, the field
+// would silently become a second, worse copy of facts the AST already models.
+//
+//  1. Build a fixture whose declarations carry convention tags, known tags, a
+//     tag with no text, and a multi-line reason, across a function, a class, a
+//     class member, an interface member, a variable, a namespace member, and a
+//     closure.
+//  2. Assert every unrecognized tag is recorded on its own declaration's node.
+//  3. Assert no known tag is recorded, and that an untagged declaration
+//     contributes nothing.
+func TestDocTagsCaptureEveryUnrecognizedTag(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), `/**
+ * Renders the notice.
+ *
+ * @evidence docs/discount.md#coupon-stacking States the per-issuer limit
+ *           this section defines, in the buyer's words.
+ * @evidenceExclude prisma:Coupon.issuedAt Not surfaced here.
+ * @param unused Ignored by the graph.
+ * @returns Nothing the graph records.
+ */
+export function renderNotice(): string {
+  return "notice";
+}
+
+/** @reference https://example.com/spec Reference document. */
+export class Notice {
+  /** @evidence docs/discount.md#member Member-level citation. */
+  public render(): void {}
+
+  /** @spec invented Any convention is one fact. */
+  public flag: boolean = false;
+}
+
+export interface INotice {
+  /** @evidence docs/discount.md#signature Interface member citation. */
+  render(): void;
+}
+
+/** @evidence docs/discount.md#variable Variable citation. */
+export const NOTICE_KIND = "notice";
+
+export namespace Shopping {
+  /** @evidence docs/discount.md#namespace Namespace member citation. */
+  export function inner(): void {}
+}
+
+export function withClosure(): void {
+  /** @evidence docs/discount.md#closure Declared inside a body. */
+  function inner(): void {}
+  inner();
+}
+
+/** Ordinary documentation with no tag at all. */
+export function untagged(): void {}
+
+/** @bare */
+export function bareTag(): void {}
+`)
+
+  prog, diags, err := driver.LoadProgram(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  if len(diags) != 0 {
+    t.Fatalf("unexpected diagnostics: %v", diags)
+  }
+  defer func() { _ = prog.Close() }()
+
+  tags := docTagsByTargetSuffix(Build(prog))
+
+  assertDocTag(t, tags, "#renderNotice:function", "evidence",
+    "docs/discount.md#coupon-stacking States the per-issuer limit this section defines, in the buyer's words.")
+  assertDocTag(t, tags, "#renderNotice:function", "evidenceExclude",
+    "prisma:Coupon.issuedAt Not surfaced here.")
+  assertDocTag(t, tags, "#Notice:class", "reference",
+    "https://example.com/spec Reference document.")
+  assertDocTag(t, tags, "#Notice.render:method", "evidence",
+    "docs/discount.md#member Member-level citation.")
+  assertDocTag(t, tags, "#Notice.flag:variable", "spec",
+    "invented Any convention is one fact.")
+  assertDocTag(t, tags, "#INotice.render:method", "evidence",
+    "docs/discount.md#signature Interface member citation.")
+  assertDocTag(t, tags, "#NOTICE_KIND:variable", "evidence",
+    "docs/discount.md#variable Variable citation.")
+  assertDocTag(t, tags, "#Shopping.inner:function", "evidence",
+    "docs/discount.md#namespace Namespace member citation.")
+  // A function declared inside a body is a node the graph records, so a tag on
+  // it is a fact like any other. It is reached through the same single
+  // collection point, which is why no declaration form needs its own handling.
+  assertDocTag(t, tags, "#withClosure.inner:function", "evidence",
+    "docs/discount.md#closure Declared inside a body.")
+  // A tag with a name and no text is a written fact; dropping it would report
+  // the declaration as carrying nothing, which is a different claim.
+  assertDocTag(t, tags, "#bareTag:function", "bare", "")
+
+  for _, known := range []string{"param", "returns"} {
+    for target, list := range tags {
+      for _, tag := range list {
+        if tag.Name == known {
+          t.Fatalf("recorded known tag %q on %s; only tags the parser could not interpret belong here", known, target)
+        }
+      }
+    }
+  }
+  for target, list := range tags {
+    if suffixMatch(target, "#untagged:function") && len(list) > 0 {
+      t.Fatalf("untagged declaration carries %d tags", len(list))
+    }
+  }
+}
+
+// docTagsByTargetSuffix groups a built graph's tags by their target node id.
+func docTagsByTargetSuffix(g *Graph) map[string][]*DocTag {
+  out := map[string][]*DocTag{}
+  for _, tag := range g.DocTags {
+    out[tag.Target] = append(out[tag.Target], tag)
+  }
+  return out
+}
+
+// assertDocTag fails unless exactly one tag with this name sits on the node
+// whose id ends with suffix, carrying text.
+func assertDocTag(t *testing.T, tags map[string][]*DocTag, suffix, name, text string) {
+  t.Helper()
+  found := 0
+  for target, list := range tags {
+    if !suffixMatch(target, suffix) {
+      continue
+    }
+    for _, tag := range list {
+      if tag.Name != name {
+        continue
+      }
+      found++
+      if tag.Text != text {
+        t.Fatalf("%s @%s text = %q, want %q", suffix, name, tag.Text, text)
+      }
+    }
+  }
+  if found != 1 {
+    t.Fatalf("%s @%s recorded %d times, want 1", suffix, name, found)
+  }
+}
+
+func suffixMatch(value, suffix string) bool {
+  return len(value) >= len(suffix) && value[len(value)-len(suffix):] == suffix
+}

package/internal/graph/doc_tags_read_only_what_the_parser_attached_test.go

@@ -0,0 +1,97 @@
+package graph
+
+import (
+  "path/filepath"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestDocTagsReadOnlyWhatTheParserAttached verifies the boundary cases that
+// decide whether a tag-shaped run of text is a fact about a declaration.
+//
+// Every case here is one a text scan would get wrong, and a wrong answer is
+// silent in both directions: a tag adopted from a line comment or from prose
+// attributes a citation to code that never made it, while a tag lost from a
+// merged declaration reports the declaration as citing nothing. The parser
+// already decides which block belongs to which declaration, so this pins that
+// the collection follows it rather than re-deciding.
+//
+//  1. Build a fixture with a tag in a line comment, a tag written mid-sentence
+//     inside a documentation block, an overload run documented on its
+//     signature, and a link tag whose braced form must survive verbatim.
+//  2. Assert the line comment contributes nothing and the mid-sentence one is
+//     the tag the parser says it is.
+//  3. Assert the overload keeps its signature's tag and the link keeps its
+//     braces.
+func TestDocTagsReadOnlyWhatTheParserAttached(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), `export interface ISale {
+  price: number;
+}
+
+// @evidence docs/a.md#line A line comment is not documentation.
+export function fromLineComment(): void {}
+
+/**
+ * Explains that an @evidence tag names a document, without being one.
+ */
+export function fromProse(): void {}
+
+/** @evidence docs/a.md#overload Documented on the signature. */
+export function overloaded(value: string): string;
+export function overloaded(value: number): string;
+export function overloaded(value: string | number): string {
+  return String(value);
+}
+
+/** @evidence {@link ISale} The contract is mirrored here. */
+export function linked(): void {}
+
+/** @evidence {@linkcode ISale} And in code form. */
+export function linkedCode(): void {}
+`)
+
+  prog, diags, err := driver.LoadProgram(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  if len(diags) != 0 {
+    t.Fatalf("unexpected diagnostics: %v", diags)
+  }
+  defer func() { _ = prog.Close() }()
+
+  tags := docTagsByTargetSuffix(Build(prog))
+
+  // A `//` comment is not documentation, so the parser attaches it to nothing
+  // and no tag can be read out of it.
+  for target, list := range tags {
+    if suffixMatch(target, "#fromLineComment:function") && len(list) > 0 {
+      t.Fatalf("line comment produced %d tags; only a documentation block attaches one", len(list))
+    }
+  }
+
+  // A tag written mid-sentence is still a tag, because TypeScript's own parser
+  // opens one at the `@` wherever it sits. This is deliberately not second-
+  // guessed: the population is "what the parser could not interpret", and a
+  // graph that re-decided where a tag may begin would be reinterpreting the
+  // compiler rather than reporting it. A convention that wants the stricter
+  // rule — the tag must open its line — enforces that in its own rule, where the
+  // author gets a diagnostic; here the fact is simply reported as parsed.
+  assertDocTag(t, tags, "#fromProse:function", "evidence",
+    "tag names a document, without being one.")
+
+  // The implementation signature carries no block of its own. Collecting tags
+  // outside the node-creation branch is what keeps the overload run's
+  // documentation, which is written on the first signature.
+  assertDocTag(t, tags, "#overloaded:function", "evidence",
+    "docs/a.md#overload Documented on the signature.")
+
+  // A citation target is matched by the token the author wrote, so the braces
+  // and the link keyword have to survive the round trip through the AST.
+  assertDocTag(t, tags, "#linked:function", "evidence",
+    "{@link ISale} The contract is mirrored here.")
+  assertDocTag(t, tags, "#linkedCode:function", "evidence",
+    "{@linkcode ISale} And in code form.")
+}

package/internal/graph/doc_tags_stop_at_the_external_boundary_test.go

@@ -0,0 +1,59 @@
+package graph
+
+import (
+  "path/filepath"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestDocTagsStopAtTheExternalBoundary verifies that a documentation tag written
+// in a dependency contributes nothing.
+//
+// The graph's boundary is the workspace: a dependency's declaration enters only
+// as a named endpoint, never walked into. A tag read from one would put a
+// citation the consumer did not write into their index — answering "which code
+// implements this specification" with somebody else's code — and it would do so
+// silently, because the address would look like any other. The collector reaches
+// only declarations the build pass records, so this holds by construction; the
+// test is here because "by construction" is what stops being true when the
+// construction changes.
+//
+//  1. Build a fixture whose `node_modules` dependency carries a tag and whose
+//     workspace source carries another.
+//  2. Assert the workspace tag is recorded.
+//  3. Assert no tag is recorded from the dependency, under any target.
+func TestDocTagsStopAtTheExternalBoundary(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), nodeModulesGlobalFixtureTSConfig)
+  writeFile(t, filepath.Join(root, "node_modules", "dep", "globals.ts"), `/** @evidence docs/vendor.md#theirs Written by the dependency. */
+export function vendored(): void {}
+`)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), `/** @evidence docs/ours.md#mine Written here. */
+export function ours(): void {}
+`)
+
+  prog, diags, err := driver.LoadProgram(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  if len(diags) != 0 {
+    t.Fatalf("unexpected diagnostics: %v", diags)
+  }
+  defer func() { _ = prog.Close() }()
+
+  tags := docTagsByTargetSuffix(Build(prog))
+
+  assertDocTag(t, tags, "#ours:function", "evidence", "docs/ours.md#mine Written here.")
+
+  for target, list := range tags {
+    for _, tag := range list {
+      if strings.Contains(target, "node_modules") ||
+        strings.Contains(tag.Text, "docs/vendor.md") {
+        t.Fatalf("recorded %s from %s; a dependency's citation is not this project's",
+          tag.Text, target)
+      }
+    }
+  }
+}

package/internal/graph/doc_tags_survive_line_endings_and_repeated_blocks_test.go

@@ -0,0 +1,146 @@
+package graph
+
+import (
+  "path/filepath"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestDocTagsSurviveLineEndingsAndRepeatedBlocks verifies the boundary cases
+// where one declaration's tags can be silently lost or doubled.
+//
+// Each is invisible when wrong. A CRLF checkout that joined a reason
+// differently would make the same source produce different index entries on
+// Windows and POSIX, so a citation found on one machine would be missing on the
+// other. A merged identity declared twice keeps whichever declarations the walk
+// reached, and a `var` redeclaration is the one shape where the same identity
+// carries two documentation blocks that both have to survive. A link written
+// with trailing text inside its braces is reassembled from two fields, so the
+// text can be dropped without the target changing.
+//
+//  1. Build a fixture with CRLF sources, a redeclared `var` documented twice, a
+//     multi-binding statement, a declaration carrying two documentation blocks,
+//     and a link carrying trailing text.
+//  2. Assert the CRLF reason joins exactly as its LF twin does.
+//  3. Assert both blocks of the merged identity are kept, every binding of the
+//     statement carries its documentation, and the link keeps its text.
+func TestDocTagsSurviveLineEndingsAndRepeatedBlocks(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
+
+  lf := `export interface ISale {
+  price: number;
+}
+
+/**
+ * Renders it.
+ *
+ * @evidence docs/a.md#reason States the limit
+ *           this section defines.
+ */
+export function joined(): void {}
+
+/** @evidence {@link ISale the sale contract} And prose after it. */
+export function linkText(): void {}
+
+/** @evidence docs/a.md#first The first declaration. */
+export var merged: number;
+/** @evidence docs/a.md#second The second declaration. */
+export var merged: number;
+
+/** @evidence docs/a.md#shared Documents the whole statement. */
+export var first = 1,
+  second = 2;
+
+/** @evidence docs/a.md#one First block. */
+/** @evidence docs/a.md#two Second block on the same declaration. */
+export function twoBlocks(): void {}
+`
+  // The shared fixture config names one root, and the CRLF twin has to be the
+  // same declarations rather than a second set, so the two spellings compile as
+  // two projects instead of two files of one.
+  writeFile(t, filepath.Join(root, "src", "main.ts"), lf)
+  crlfRoot := t.TempDir()
+  writeFile(t, filepath.Join(crlfRoot, "tsconfig.json"), fixtureTSConfig)
+  writeFile(t, filepath.Join(crlfRoot, "src", "main.ts"),
+    strings.ReplaceAll(strings.ReplaceAll(lf, "\r\n", "\n"), "\n", "\r\n"))
+
+  prog, diags, err := driver.LoadProgram(root, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  if len(diags) != 0 {
+    t.Fatalf("unexpected diagnostics: %v", diags)
+  }
+  defer func() { _ = prog.Close() }()
+
+  crlfProg, crlfDiags, err := driver.LoadProgram(crlfRoot, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  if len(crlfDiags) != 0 {
+    t.Fatalf("unexpected CRLF diagnostics: %v", crlfDiags)
+  }
+  defer func() { _ = crlfProg.Close() }()
+
+  byRoot := map[string]map[string][]*DocTag{
+    "LF":   docTagsByTargetSuffix(Build(prog)),
+    "CRLF": docTagsByTargetSuffix(Build(crlfProg)),
+  }
+
+  // A reason written across two comment lines is one string, under both
+  // spellings of a line terminator.
+  for spelling, tags := range byRoot {
+    assertDocTagIn(t, tags, spelling, "#joined:function", "evidence",
+      "docs/a.md#reason States the limit this section defines.")
+    assertDocTagIn(t, tags, spelling, "#linkText:function", "evidence",
+      "{@link ISale the sale contract} And prose after it.")
+    // Both declarations of one identity contribute: collecting inside the
+    // node-creation branch would have kept whichever won the display span.
+    assertDocTagIn(t, tags, spelling, "#merged:variable", "evidence",
+      "docs/a.md#first The first declaration.")
+    assertDocTagIn(t, tags, spelling, "#merged:variable", "evidence",
+      "docs/a.md#second The second declaration.")
+    // One statement documents every binding it declares: the text sits above
+    // the statement and nothing in the source assigns it to the first name.
+    assertDocTagIn(t, tags, spelling, "#first:variable", "evidence",
+      "docs/a.md#shared Documents the whole statement.")
+    assertDocTagIn(t, tags, spelling, "#second:variable", "evidence",
+      "docs/a.md#shared Documents the whole statement.")
+    // TypeScript attaches more than one documentation block to a declaration
+    // when more than one is written, and each is a place a tag can sit. Reading
+    // only the last would silently drop the first.
+    assertDocTagIn(t, tags, spelling, "#twoBlocks:function", "evidence",
+      "docs/a.md#one First block.")
+    assertDocTagIn(t, tags, spelling, "#twoBlocks:function", "evidence",
+      "docs/a.md#two Second block on the same declaration.")
+  }
+}
+
+// assertDocTagIn fails unless a tag with this name and text sits on the node
+// whose id ends with suffix, naming the source spelling in the failure.
+func assertDocTagIn(t *testing.T, tags map[string][]*DocTag, spelling, suffix, name, text string) {
+  t.Helper()
+  for target, list := range tags {
+    if !suffixMatch(target, suffix) {
+      continue
+    }
+    for _, tag := range list {
+      if tag.Name == name && tag.Text == text {
+        return
+      }
+    }
+    t.Fatalf("%s %s carries %s, want @%s %q", spelling, suffix, renderDocTags(list), name, text)
+  }
+  t.Fatalf("%s %s recorded no tags at all, want @%s %q", spelling, suffix, name, text)
+}
+
+func renderDocTags(list []*DocTag) string {
+  out := make([]string, 0, len(list))
+  for _, tag := range list {
+    out = append(out, "@"+tag.Name+" "+tag.Text)
+  }
+  return "[" + strings.Join(out, " | ") + "]"
+}

package/internal/graph/dump.go

@@ -57,6 +57,15 @@ type DumpDecorator struct {
   Arguments []DumpDecoratorArgument `json:"arguments"`
 }
 
+// DumpDocTag is one documentation tag TypeScript does not recognize, carried on
+// the declaration it was written on. `name` is the tag without its `@` and
+// `text` is everything after it, joined into one line. Neither is interpreted:
+// which part of a text names a thing belongs to whichever convention wrote it.
+type DumpDocTag struct {
+  Name string `json:"name"`
+  Text string `json:"text,omitempty"`
+}
+
 // DumpEnumMember is one member of an enum on the wire: the name a caller writes
 // and the value it carries. `value` is omitted for a member the checker could
 // not fold to a constant — the name still stands, and the name is what a caller
@@ -89,19 +98,25 @@ type DumpNode struct {
   // and stopped early when the head itself contained a brace — a type-literal
   // parameter, an object return type, a destructured parameter. Neither is a
   // guess the consumer can win, so the producer renders it here.
-  Signature      string             `json:"signature,omitempty"`
-  File           string             `json:"file"`
-  External       bool               `json:"external"`
-  Ignored        bool               `json:"ignored,omitempty"`
-  Exported       bool               `json:"exported,omitempty"`
-  Closure        bool               `json:"closure,omitempty"`
-  Modifiers      []string           `json:"modifiers,omitempty"`
-  Literals       []string           `json:"literals,omitempty"`
-  EnumMembers    []DumpEnumMember   `json:"enumMembers,omitempty"`
-  ObjectMembers  []DumpObjectMember `json:"objectMembers,omitempty"`
-  Evidence       *DumpEvidence      `json:"evidence,omitempty"`
-  Implementation *DumpEvidence      `json:"implementation,omitempty"`
-  Decorators     []DumpDecorator    `json:"decorators,omitempty"`
+  Signature     string             `json:"signature,omitempty"`
+  File          string             `json:"file"`
+  External      bool               `json:"external"`
+  Ignored       bool               `json:"ignored,omitempty"`
+  Exported      bool               `json:"exported,omitempty"`
+  Closure       bool               `json:"closure,omitempty"`
+  Modifiers     []string           `json:"modifiers,omitempty"`
+  Literals      []string           `json:"literals,omitempty"`
+  EnumMembers   []DumpEnumMember   `json:"enumMembers,omitempty"`
+  ObjectMembers []DumpObjectMember `json:"objectMembers,omitempty"`
+  // Parent is the artifact containing this one, and is empty for every
+  // declaration: a declaration's containment is synthesized by the TypeScript
+  // memory layer, and two producers of one relation would put two answers in
+  // the graph.
+  Parent         string          `json:"parent,omitempty"`
+  Evidence       *DumpEvidence   `json:"evidence,omitempty"`
+  Implementation *DumpEvidence   `json:"implementation,omitempty"`
+  Decorators     []DumpDecorator `json:"decorators,omitempty"`
+  DocTags        []DumpDocTag    `json:"docTags,omitempty"`
 }
 
 // DumpEdge is the wire shape of a graph edge. Lowercase json keys are the
@@ -233,6 +248,13 @@ func newDumpFacts(g *Graph, project string, ignored map[string]bool, sources map
     decByNode[d.Target] = append(decByNode[d.Target], DumpDecorator{Name: d.Name, Arguments: args})
   }
 
+  // Documentation tags ride on their target node the same way, grouped before
+  // relativization for the same reason.
+  tagsByNode := make(map[string][]DumpDocTag, len(g.DocTags))
+  for _, t := range g.DocTags {
+    tagsByNode[t.Target] = append(tagsByNode[t.Target], DumpDocTag{Name: t.Name, Text: t.Text})
+  }
+
   nodes := make([]DumpNode, 0, len(g.Nodes))
   for _, n := range g.Nodes {
     name, qualified := nodeNames(n)
@@ -241,6 +263,28 @@ func newDumpFacts(g *Graph, project string, ignored map[string]bool, sources map
     if n.Kind == NodeModule {
       name, qualified = ctx.rel(name), ""
     }
+    // An artifact's id IS the address a citation names, so it is emitted
+    // verbatim: relativizing it would rewrite `prisma:Sale.price`, which carries
+    // no path on purpose, and `POST:/orders`, which has no file at all. Its name
+    // is the readable heading the plugin reported, and its span is the single
+    // line where that heading starts — never the section's content.
+    if IsArtifactKind(n.Kind) {
+      artifact := DumpNode{
+        ID:     n.ID,
+        Kind:   string(n.Kind),
+        Name:   n.Simple,
+        File:   ctx.rel(n.File),
+        Parent: n.ArtifactParent,
+      }
+      if artifact.Name == "" {
+        artifact.Name = n.Name
+      }
+      if n.ArtifactLine > 0 {
+        artifact.Evidence = &DumpEvidence{StartLine: n.ArtifactLine}
+      }
+      nodes = append(nodes, artifact)
+      continue
+    }
     nodes = append(nodes, DumpNode{
       ID:            ctx.relID(n.ID),
       Kind:          string(n.Kind),
@@ -261,6 +305,7 @@ func newDumpFacts(g *Graph, project string, ignored map[string]bool, sources map
       Evidence:       withoutFile(ctx.evidence(n.File, n.Pos, n.End)),
       Implementation: ctx.evidence(n.ImplementationFile, n.ImplementationPos, n.ImplementationEnd),
       Decorators:     decByNode[n.ID],
+      DocTags:        tagsByNode[n.ID],
     })
   }
   sort.Slice(nodes, func(i, j int) bool { return nodes[i].ID < nodes[j].ID })
@@ -398,6 +443,8 @@ func wireEdgeKind(kind EdgeKind, origin string) string {
     return "accesses"
   case EdgeTypeRef:
     return "type_ref"
+  case EdgeDocRef:
+    return "doc_ref"
   case EdgeHeritage:
     if origin == "extends" {
       return "extends"

package/internal/graph/dump_checkout_paths_are_stable_test.go

@@ -20,7 +20,7 @@ const portableDumpTSConfig = `{
 }
 `
 
-// TestDumpCheckoutPathsAreStable verifies the whole schema-v6 consequence
+// TestDumpCheckoutPathsAreStable verifies the whole dump-identity consequence
 // surface, not only the path helper.
 //
 //  1. Build the same project plus sibling .ts/.d.ts under two checkout roots.
@@ -51,7 +51,7 @@ func TestDumpCheckoutPathsAreStable(t *testing.T) {
   assertPortableFixturePaths(t, first)
   if strings.Contains(string(firstJSON), filepath.ToSlash(firstCheckout)) ||
     strings.Contains(string(secondJSON), filepath.ToSlash(secondCheckout)) {
-    t.Fatal("a producer-local checkout path escaped into schema-v6 identity")
+    t.Fatal("a producer-local checkout path escaped into dump identity")
   }
 }
 

package/internal/graph/dump_paths.go

@@ -9,7 +9,7 @@ import (
   shimtspath "github.com/microsoft/typescript-go/shim/tspath"
 )
 
-// dumpPathMapper owns the schema-v6 path vocabulary for one dump. Every
+// dumpPathMapper owns the dump path vocabulary for one dump. Every
 // identity-bearing path passes through this one cache, so the producer can
 // reject both an unportable filesystem root and a non-injective projection
 // before any JSON is written.
@@ -50,7 +50,7 @@ func WireProject(project string) (string, error) {
   return mapper.project, mapper.err()
 }
 
-// WirePath maps one compiler path into the portable schema-v6 vocabulary used
+// WirePath maps one compiler path into the portable dump vocabulary used
 // by dumps and resident graph shards. Callers that project a complete graph
 // keep one dumpPathMapper so collision detection spans every path; callers
 // shaping a single source/config coordinate use this helper and receive the

package/internal/graph/dump_paths_are_portable_and_injective_test.go

@@ -5,7 +5,7 @@ import (
   "testing"
 )
 
-// TestDumpPathMapperUsesPortableCoordinates verifies the schema-v6 vocabulary
+// TestDumpPathMapperUsesPortableCoordinates verifies the dump path vocabulary
 // directly, independent of the host OS running the test.
 //
 //  1. Map in-project and sibling paths for POSIX, drive, and UNC layouts.