ttsc 0.27.0 → 0.28.1

package/internal/graph/doc_tags.go

@@ -0,0 +1,416 @@
+package graph
+
+import (
+  "strings"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+// DocTag is one documentation tag TypeScript itself does not recognize, written
+// on a workspace declaration and captured verbatim.
+//
+// A convention attaches a declaration to something outside the type system — a
+// specification section, an API operation, a reference document — and writes
+// that attachment as a tag. `@evidence docs/pricing.md#sale`, `@reference
+// https://…`, and a consumer's own `@spec` are the same fact in three
+// spellings, and none of them is expressible as an edge because the thing on
+// the other end is not a TypeScript declaration.
+//
+// The population is defined by the compiler rather than by us: these are the
+// tags the parser had no meaning for, so it kept them as
+// KindJSDocUnknownTag. A known tag — `@param`, `@returns`, `@deprecated` — has
+// its own AST shape and its own meaning and is not this. Naming particular tags
+// here would make the compiler host know one convention, and would have left
+// out the 767 `@reference` tags this repository's own sources carry.
+//
+// Nothing is interpreted. Target is not split out of Text, because which part
+// of a tag's text names a thing is a convention's rule and this pass enforces
+// none; a consumer that ranks on a leading token does so in the layer that
+// declares its selection heuristic. This is the contract Decorator already
+// keeps for `@Controller`/`@Get`.
+type DocTag struct {
+  // Target is the id of the graph node the tag was written on.
+  Target string
+  // Name is the tag name without its `@` (`evidence`, `evidenceExclude`,
+  // `reference`).
+  Name string
+  // Text is everything after the tag name, with the comment's leading asterisks
+  // and per-line indentation removed and its lines joined by single spaces.
+  // Empty when the tag carries no text.
+  Text string
+  // Pos and End bound the written tag. They are not published — a tag rides its
+  // target node, which carries the span a reader cites — and exist so one
+  // declaration presented to the node pass twice contributes its tags once.
+  Pos int
+  End int
+}
+
+// collectDocTags records a DocTag for every unrecognized documentation tag on
+// declaration, attributed to the graph node identified by targetID.
+//
+// It runs from putDeclaredNode rather than from a pass of its own, so every
+// declaration form the build records — a function, a class, an interface member,
+// a variable binding, a closure, a namespace member — carries its tags without
+// each form having to remember to ask. A merged identity therefore accumulates
+// the tags of every declaration that names it: an overload run documented on its
+// signature and implemented below keeps the signature's tags, which putting this
+// inside the node-creation branch would have dropped.
+//
+// Positions deduplicate, because the same declaration node can be presented to
+// putDeclaredNode more than once and a tag is a property of where it is written.
+func collectDocTags(g *Graph, targetID string, declaration *shimast.Node) {
+  if g == nil || declaration == nil || targetID == "" {
+    return
+  }
+  file := shimast.GetSourceFileOfNode(declaration)
+  if file == nil {
+    return
+  }
+  docs := documentationOf(declaration, file)
+  if len(docs) == 0 {
+    return
+  }
+  g.recordDocHost(targetID, declaration)
+  if g.docTagPositions == nil {
+    g.docTagPositions = map[docTagKey]struct{}{}
+  }
+  for _, doc := range docs {
+    if doc == nil || doc.Kind != shimast.KindJSDoc {
+      continue
+    }
+    comment := doc.AsJSDoc()
+    if comment == nil || comment.Tags == nil {
+      continue
+    }
+    for _, tag := range comment.Tags.Nodes {
+      fact := docTagFact(tag)
+      if fact == nil {
+        continue
+      }
+      fact.Target = targetID
+      key := docTagKey{target: targetID, pos: fact.Pos, end: fact.End}
+      if _, seen := g.docTagPositions[key]; seen {
+        continue
+      }
+      g.docTagPositions[key] = struct{}{}
+      g.DocTags = append(g.DocTags, fact)
+    }
+  }
+}
+
+// documentationOf returns the documentation blocks that describe declaration.
+//
+// A variable's block is the one place the node the graph records and the node
+// the parser attached the documentation to are different. TypeScript attaches
+// one leading block to the variable *statement*, while the graph records a node
+// per binding, so asking the binding directly finds nothing and every citation
+// written on a `const` was lost. The statement is reached through its
+// declaration list, and both hops are checked rather than assumed.
+//
+// One statement can declare several bindings (`export const a = 1, b = 2`), and
+// then its block genuinely documents all of them: the text is above the
+// statement, and nothing in the source says it belongs to the first binding
+// only. Each binding's node therefore carries it, which is the same answer the
+// evidence host model reaches from the other direction.
+//
+// The walk stops there. A binding element inside a destructuring pattern is
+// given no documentation by the parser, so climbing further would invent an
+// association the source does not make.
+func documentationOf(declaration *shimast.Node, file *shimast.SourceFile) []*shimast.Node {
+  if docs := declaration.JSDoc(file); len(docs) > 0 {
+    return docs
+  }
+  if declaration.Kind != shimast.KindVariableDeclaration {
+    return nil
+  }
+  list := declaration.Parent
+  if list == nil || list.Kind != shimast.KindVariableDeclarationList {
+    return nil
+  }
+  statement := list.Parent
+  if statement == nil || statement.Kind != shimast.KindVariableStatement {
+    return nil
+  }
+  return statement.JSDoc(file)
+}
+
+// docTagKey identifies one written tag on one target, so a declaration visited
+// twice contributes its tags once.
+type docTagKey struct {
+  target string
+  pos    int
+  end    int
+}
+
+// docTagFact reads one tag node into a DocTag, or nil when the tag is one
+// TypeScript recognizes or carries no usable name.
+func docTagFact(tag *shimast.Node) *DocTag {
+  if tag == nil || tag.Kind != shimast.KindJSDocUnknownTag {
+    return nil
+  }
+  unknown := tag.AsJSDocUnknownTag()
+  if unknown == nil || unknown.TagName == nil {
+    return nil
+  }
+  name := unknown.TagName.Text()
+  if name == "" {
+    return nil
+  }
+  return &DocTag{
+    Name: name,
+    Text: docTagText(unknown.Comment),
+    Pos:  tag.Pos(),
+    End:  tag.End(),
+  }
+}
+
+// docTagText renders a tag's comment list as one line.
+//
+// A tag's text is a list of comment nodes: plain text runs, and link nodes for
+// `{@link Foo}` and its two variants. The link nodes are rendered back to the
+// braced form they were written in, because a consumer matching a citation
+// target has to see the target as the author wrote it — and because the same
+// link is separately available as a resolved edge, so dropping the text here
+// would leave the two halves unable to be read together.
+//
+// Lines join with single spaces. A documentation comment carries its own
+// leading asterisks and indentation on every line after the first, and neither
+// is content; joining on a space is also what makes a reason written across
+// three lines one string rather than three.
+func docTagText(comment *shimast.NodeList) string {
+  if comment == nil {
+    return ""
+  }
+  var out strings.Builder
+  for _, node := range comment.Nodes {
+    if node == nil {
+      continue
+    }
+    switch node.Kind {
+    case shimast.KindJSDocLink:
+      writeDocTagLink(&out, "{@link ", node)
+    case shimast.KindJSDocLinkCode:
+      writeDocTagLink(&out, "{@linkcode ", node)
+    case shimast.KindJSDocLinkPlain:
+      writeDocTagLink(&out, "{@linkplain ", node)
+    default:
+      out.WriteString(shimast.NodeText(node))
+    }
+  }
+  return joinDocTagLines(out.String())
+}
+
+// writeDocTagLink renders one link node back to its written form. The name and
+// the trailing text are separate fields on the node, so `{@link A.B rest}` is
+// reassembled rather than read off one string.
+func writeDocTagLink(out *strings.Builder, opener string, node *shimast.Node) {
+  name := ""
+  switch node.Kind {
+  case shimast.KindJSDocLink:
+    if link := node.AsJSDocLink(); link != nil && link.Name() != nil {
+      name = shimast.NodeText(link.Name())
+    }
+  case shimast.KindJSDocLinkCode:
+    if link := node.AsJSDocLinkCode(); link != nil && link.Name() != nil {
+      name = shimast.NodeText(link.Name())
+    }
+  case shimast.KindJSDocLinkPlain:
+    if link := node.AsJSDocLinkPlain(); link != nil && link.Name() != nil {
+      name = shimast.NodeText(link.Name())
+    }
+  }
+  out.WriteString(opener)
+  out.WriteString(name)
+  text := shimast.NodeText(node)
+  if text != "" {
+    if name != "" {
+      out.WriteString(" ")
+    }
+    out.WriteString(text)
+  }
+  out.WriteString("}")
+}
+
+// joinDocTagLines collapses a tag's physical lines into one and normalizes the
+// whitespace runs a documentation comment adds around them.
+//
+// strings.Fields splits on every Unicode space, which covers the four
+// ECMAScript line terminators — LF, CR, U+2028, U+2029 — so a CRLF checkout and
+// an LF one produce the same string, and a reason written across three comment
+// lines becomes one.
+func joinDocTagLines(text string) string {
+  return strings.Join(strings.Fields(text), " ")
+}
+
+// collectDocRefs records an edge from each declaration to the symbols its own
+// documentation names through an inline link.
+//
+// The checker resolves such a name and counts it as a use — a `noUnusedLocals`
+// project keeps an import that exists only to support a link — so this is a
+// compiler fact, not a text match, and it was the one class of resolved
+// reference the graph held no edge for. The link node carries an EntityName,
+// which is the node class typeRefEdge already resolves, so the resolution and
+// the external-boundary and self-reference rules are the existing ones.
+//
+// Links are read from the whole documentation comment rather than from tags
+// alone: a link under `@evidence`, under `@see`, and in ordinary prose are one
+// relation, and privileging a tag would put one convention's name inside the
+// compiler host.
+func (g *Graph) collectDocRefs(checker *shimchecker.Checker, file *shimast.SourceFile) {
+  for _, host := range g.docHosts[file.FileName()] {
+    for _, doc := range documentationOf(host.declaration, file) {
+      g.docRefsWithin(checker, host.target, doc)
+    }
+  }
+}
+
+// recordDocHost remembers that a declaration carries documentation, so the edge
+// pass resolves its links from exactly the declarations the build pass
+// attributed documentation to.
+//
+// The two passes cannot share a walk — one runs before the checker exists and
+// the other needs it — so they would otherwise share only a convention, and a
+// convention is what drifted. The container walk the edge pass would naturally
+// reuse never visits a class, an interface, or a namespace as a node of its
+// own: it descends straight into their members. So a link written on a class's
+// own documentation resolved to nothing while the tag beside it was indexed,
+// and the two halves a reader is meant to compose disagreed exactly where a
+// type is documented. Recording the host here means the edge pass covers every
+// declaration form the node pass records, including forms nobody has written
+// yet.
+//
+// It also fixes the attribution: the container walk hands a property member's
+// subtree to the property *and* to its class, which is deliberate for the
+// dependency edges but would make a class's documentation appear to name a
+// symbol only its member's documentation mentions.
+func (g *Graph) recordDocHost(target string, declaration *shimast.Node) {
+  file := shimast.GetSourceFileOfNode(declaration)
+  if file == nil {
+    return
+  }
+  key := docTagKey{target: target, pos: declaration.Pos(), end: declaration.End()}
+  if g.docHostPositions == nil {
+    g.docHostPositions = map[docTagKey]struct{}{}
+  }
+  if _, seen := g.docHostPositions[key]; seen {
+    return
+  }
+  g.docHostPositions[key] = struct{}{}
+  if g.docHosts == nil {
+    g.docHosts = map[string][]docHost{}
+  }
+  path := file.FileName()
+  g.docHosts[path] = append(g.docHosts[path], docHost{
+    target:      target,
+    declaration: declaration,
+  })
+}
+
+// docHost is one declaration that carries documentation, paired with the graph
+// node the build pass attributed it to. They are grouped by file, because the
+// edge pass asks once per file and a flat slice would make that a scan of every
+// documented declaration in the project for each one.
+type docHost struct {
+  target      string
+  declaration *shimast.Node
+}
+
+// docRefsWithin resolves every inline link inside one documentation comment.
+//
+// The walk descends through each tag with ForEachChild rather than reading a
+// tag's comment field, because that field lives on a per-kind struct: a
+// type-asserted read crashes on the first `@param` it meets, and a switch over
+// the kinds that carry one would cover the thirty tag shapes TypeScript models
+// only until it missed one. Every tag node visits its own comment list, so one
+// recursion reaches a link under `@evidence`, under `@see`, and under whatever
+// tag a consumer invents, which is the rule this edge is defined by.
+//
+// The JSDoc node itself reports no children, so its prose comment is walked
+// explicitly beside the tags; that is the same reason the existing edge passes
+// never reached a link.
+func (g *Graph) docRefsWithin(checker *shimchecker.Checker, from string, doc *shimast.Node) {
+  // Guarded on the kind before the conversion, the way the tag walk is. A
+  // documentation block is what this is handed and an AsJSDoc on anything else
+  // panics rather than returning nil — which is exactly how reading a tag's
+  // comment through its own struct crashed on the first `@param`.
+  if doc == nil || doc.Kind != shimast.KindJSDoc {
+    return
+  }
+  comment := doc.AsJSDoc()
+  if comment == nil {
+    return
+  }
+  g.docRefsInComment(checker, from, comment.Comment)
+  if comment.Tags == nil {
+    return
+  }
+  for _, tag := range comment.Tags.Nodes {
+    g.docRefsInSubtree(checker, from, tag)
+  }
+}
+
+// docRefsInSubtree resolves the links anywhere under one documentation node.
+func (g *Graph) docRefsInSubtree(checker *shimchecker.Checker, from string, node *shimast.Node) {
+  if node == nil {
+    return
+  }
+  if name := docLinkName(node); name != nil {
+    g.docRefEdge(checker, from, name)
+    // A link's own subtree is the name just resolved; descending would resolve
+    // it a second time under a different node.
+    return
+  }
+  node.ForEachChild(func(child *shimast.Node) bool {
+    g.docRefsInSubtree(checker, from, child)
+    return false
+  })
+}
+
+// docRefsInComment resolves the link nodes in one comment list.
+func (g *Graph) docRefsInComment(checker *shimchecker.Checker, from string, comment *shimast.NodeList) {
+  if comment == nil {
+    return
+  }
+  for _, node := range comment.Nodes {
+    g.docRefsInSubtree(checker, from, node)
+  }
+}
+
+// docLinkName returns the entity name a link node points at, or nil for a
+// comment node that is not a link or a link that names nothing — `{@link}` with
+// only text is a formatting choice, not a reference.
+func docLinkName(node *shimast.Node) *shimast.Node {
+  if node == nil {
+    return nil
+  }
+  switch node.Kind {
+  case shimast.KindJSDocLink:
+    if link := node.AsJSDocLink(); link != nil {
+      return link.Name()
+    }
+  case shimast.KindJSDocLinkCode:
+    if link := node.AsJSDocLinkCode(); link != nil {
+      return link.Name()
+    }
+  case shimast.KindJSDocLinkPlain:
+    if link := node.AsJSDocLinkPlain(); link != nil {
+      return link.Name()
+    }
+  }
+  return nil
+}
+
+// docRefEdge resolves one link name to its declaration and records the edge,
+// skipping an unresolved name and a self-reference exactly as typeRefEdge does.
+func (g *Graph) docRefEdge(checker *shimchecker.Checker, from string, name *shimast.Node) {
+  target := g.resolve(checker, name)
+  if target == nil || target.Symbol == nil {
+    return
+  }
+  to := g.ensureTargetNode(target)
+  if to == "" || to == from {
+    return
+  }
+  g.addEdgeAt(from, to, EdgeDocRef, "", name.Pos(), name.End())
+}

package/internal/graph/doc_tags_are_claimed_before_they_are_read_test.go

@@ -0,0 +1,131 @@
+package graph
+
+import (
+  "encoding/json"
+  "path/filepath"
+  "reflect"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestDocTagsAreClaimedBeforeTheyAreRead verifies that the projection carries a
+// tag onto the wire and that a project with no tag is unchanged beside it.
+//
+// The capability the shipped commands declare is asserted where it is made, in
+// `cmd/ttscgraph`: a test that hands a capability list to the marshaller and
+// reads it back proves only that the slice was copied, and would leave the
+// production list free to lose the member with nothing failing. What this one
+// owns is the other half — that a tag reaches the document, and that a project
+// using no convention pays nothing for the feature.
+func TestDocTagsAreClaimedBeforeTheyAreRead(t *testing.T) {
+  tagged := dumpDocTagFixture(t, `/** @evidence docs/a.md#x Cited. */
+export function subject(): void {}
+`)
+  untagged := dumpDocTagFixture(t, `/** Ordinary documentation. */
+export function subject(): void {}
+`)
+
+  if got := docTagTexts(tagged); len(got) != 1 || got[0] != "docs/a.md#x Cited." {
+    t.Fatalf("tagged dump carried %v", got)
+  }
+  if got := docTagTexts(untagged); len(got) != 0 {
+    t.Fatalf("untagged dump carried %v", got)
+  }
+
+  // The rest of the untagged document is what it was: the feature costs a
+  // project using no convention exactly nothing. Compared structurally rather
+  // than by count, because equal counts survive a changed id, name, or span.
+  if !reflect.DeepEqual(strippedDocTags(tagged), untagged) {
+    t.Fatalf("the two documents differ beyond the tag: tagged %+v, untagged %+v",
+      strippedDocTags(tagged), untagged)
+  }
+}
+
+// dumpDocTagProbe is the slice of the wire contract this test reads.
+type dumpDocTagProbe struct {
+  Provenance struct {
+    Capabilities []string `json:"capabilities"`
+  } `json:"provenance"`
+  Nodes []dumpDocTagNode `json:"nodes"`
+  Edges []dumpDocTagEdge `json:"edges"`
+}
+
+type dumpDocTagNode struct {
+  ID        string       `json:"id"`
+  Kind      string       `json:"kind"`
+  Name      string       `json:"name"`
+  Signature string       `json:"signature"`
+  Evidence  any          `json:"evidence"`
+  DocTags   []DumpDocTag `json:"docTags"`
+}
+
+type dumpDocTagEdge struct {
+  From     string `json:"from"`
+  To       string `json:"to"`
+  Kind     string `json:"kind"`
+  Evidence any    `json:"evidence"`
+}
+
+// strippedDocTags is the tagged document with its tags removed, which is what
+// the untagged one must equal.
+func strippedDocTags(parsed dumpDocTagProbe) dumpDocTagProbe {
+  out := parsed
+  out.Nodes = append([]dumpDocTagNode(nil), parsed.Nodes...)
+  for index := range out.Nodes {
+    out.Nodes[index].DocTags = nil
+  }
+  return out
+}
+
+func docTagTexts(parsed dumpDocTagProbe) []string {
+  out := []string{}
+  for _, node := range parsed.Nodes {
+    for _, tag := range node.DocTags {
+      out = append(out, tag.Text)
+    }
+  }
+  return out
+}
+
+// dumpDocTagFixture builds and marshals a one-file project, returning the parsed
+// wire document.
+func dumpDocTagFixture(t *testing.T, source string) dumpDocTagProbe {
+  t.Helper()
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), source)
+
+  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() }()
+
+  g := Build(prog)
+  data, err := MarshalDump(g, root, "tsconfig.json", nil, SourceTexts(prog), DumpOrigin{
+    Provenance: NewProvenance(
+      Producer{Tool: "test", Typescript: TypescriptVersion()},
+      []string{CapabilityDocTags},
+      nil,
+      nil,
+      SourceTexts(prog),
+      nil,
+    ),
+  }, false)
+  if err != nil {
+    t.Fatal(err)
+  }
+  var parsed dumpDocTagProbe
+  if err := json.Unmarshal(data, &parsed); err != nil {
+    t.Fatal(err)
+  }
+  if !strings.Contains(string(data), "\"nodes\"") {
+    t.Fatalf("dump carried no nodes section")
+  }
+  return parsed
+}