ttsc 0.19.2 → 0.20.0

package/internal/graph/edges.go

@@ -7,11 +7,17 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// addEdges resolves the relationships between the declaration nodes Build
-// recorded. It walks each source file again and, for every class or interface,
-// resolves its heritage bases through the checker (unwrapping barrel re-exports
-// to the real declaration) and links the declaration to that base, materializing
-// an external boundary-leaf node when the base lives in node_modules or a `.d.ts`.
+// addEdges is the checker pass over the declaration nodes Build recorded. It
+// walks each source file again and, for every class or interface, resolves its
+// heritage bases through the checker (unwrapping barrel re-exports to the real
+// declaration) and links the declaration to that base, materializing an external
+// boundary-leaf node when the base lives in node_modules or a `.d.ts`.
+//
+// Not everything it resolves is an edge. A fact that belongs to one declaration
+// rather than to a pair of them rides on its own node: a decorator on the target
+// it annotates, a literal value set on the type that admits it. Both need the
+// same checker and the same walk, so they are resolved here and written to the
+// node the build pass keyed.
 func (g *Graph) addEdges(prog *driver.Program) {
   checker := prog.Checker
   for _, file := range prog.SourceFiles() {
@@ -19,6 +25,7 @@ func (g *Graph) addEdges(prog *driver.Program) {
     g.collectHeritage(checker, file)
     g.collectCalls(checker, file)
     g.collectTypeRefs(checker, file)
+    g.collectLiterals(checker, file)
     if file.Statements != nil {
       g.collectDecorators(file.FileName(), file.Statements.Nodes)
     }
@@ -115,8 +122,216 @@ func (g *Graph) heritageEdges(checker *shimchecker.Checker, path string, node *s
         continue
       }
       g.addEdgeAt(from, to, EdgeHeritage, origin, base.Expression.Pos(), base.Expression.End())
+      g.memberRelationEdges(checker, node, kind, typeNode, target, origin)
+    }
+  }
+}
+
+// memberRelationEdges records the directly declared member pairs that a
+// heritage clause makes checker-valid. The TypeScript loader used to infer
+// these from equal names after the dump was built. That made an authoritative
+// edge even when the checker rejected the container relation, and a method /
+// property kind guard could not repair it: same-kind signatures can be
+// incompatible while a method can validly satisfy a function-valued property.
+//
+// Each pair is checked independently. A whole-container assignability gate
+// would let one broken sibling erase a valid relation in the same partially
+// edited class. The pair query retains the checker's instantiated property
+// symbols, so optionality, overloads, and private/protected declaration origins
+// still use upstream propertyRelatedTo semantics.
+func (g *Graph) memberRelationEdges(
+  checker *shimchecker.Checker,
+  derivedDeclaration *shimast.Node,
+  derivedKind NodeKind,
+  baseTypeNode *shimast.Node,
+  baseTarget *Target,
+  heritageOrigin string,
+) {
+  if checker == nil || derivedDeclaration == nil || baseTypeNode == nil || baseTarget == nil || baseTarget.External {
+    return
+  }
+  derivedSymbol := derivedDeclaration.Symbol()
+  if derivedSymbol == nil || baseTarget.Symbol == nil {
+    return
+  }
+  derivedType := checker.GetDeclaredTypeOfSymbol(derivedSymbol)
+  baseType := checker.GetTypeFromTypeNode(baseTypeNode)
+  if derivedType == nil || baseType == nil {
+    return
+  }
+
+  derivedMembers := declaredTypeMembers(derivedSymbol)
+  baseMembers := declaredTypeMembers(baseTarget.Symbol)
+
+  relation := "overrides"
+  if heritageOrigin == "implements" {
+    relation = "implements"
+  }
+  for _, derivedMember := range derivedMembers {
+    derivedMemberSymbol := derivedMember.Symbol()
+    if derivedMemberSymbol == nil || derivedMemberSymbol.Name == "" ||
+      shimast.GetCombinedModifierFlags(derivedMember)&shimast.ModifierFlagsStatic != 0 ||
+      derivedMember.Kind == shimast.KindConstructor {
+      continue
+    }
+
+    derivedProperty := checker.GetPropertyOfType(derivedType, derivedMemberSymbol.Name)
+    baseProperty := checker.GetPropertyOfType(baseType, derivedMemberSymbol.Name)
+    if derivedProperty == nil || baseProperty == nil ||
+      !propertyRootsAt(checker, derivedProperty, derivedMemberSymbol) {
+      continue
+    }
+    baseMember := directMemberForProperty(checker, baseProperty, baseMembers)
+    if baseMember == nil {
+      // The heritage clause names one type; the member may live further up.
+      // `interface Child extends Root {}` with `class W implements Child`
+      // resolves `W.execute` against `Root.execute`, and the program compiles
+      // with no diagnostic — but the immediate base declares nothing, so
+      // requiring a directly declared member dropped a relation the checker
+      // had already established. Execution tracing follows these edges to
+      // reach an implementation, so the missing edge ends the trace at the
+      // abstract declaration.
+      baseMember = inheritedMemberForProperty(checker, baseProperty)
+    }
+    if baseMember == nil ||
+      !shimchecker.Checker_isPropertyAssignableTo(checker, derivedProperty, baseProperty) {
+      continue
+    }
+    if relation == "overrides" && derivedKind == NodeClass &&
+      !shimchecker.Checker_isValidClassMemberOverridePair(checker, derivedProperty, baseProperty) {
+      continue
+    }
+
+    from := graphMemberNodeID(g, derivedMember)
+    to := graphMemberNodeID(g, baseMember)
+    if from == "" || to == "" {
+      continue
+    }
+    evidence := derivedMember.Name()
+    if evidence == nil {
+      evidence = derivedMember
+    }
+    g.addEdgeAt(from, to, EdgeMemberRelation, relation, evidence.Pos(), evidence.End())
+  }
+}
+
+// declaredTypeMembers returns the members written on every class/interface
+// declaration merged into symbol. The checker sees that merged type as one
+// surface, so choosing one representative declaration would omit valid pairs
+// contributed by another declaration even though both graph nodes already
+// exist.
+func declaredTypeMembers(symbol *shimast.Symbol) []*shimast.Node {
+  if symbol == nil {
+    return nil
+  }
+  var members []*shimast.Node
+  for _, declaration := range symbol.Declarations {
+    members = append(members, classMembers(declaration)...)
+  }
+  return members
+}
+
+// inheritedMemberForProperty resolves the declaration a base type inherits
+// rather than declares, by following the property to the symbol it roots at.
+//
+// It is the fallback for what directMemberForProperty below cannot see. A
+// heritage clause names one type and the member may be declared further up:
+// `interface Child extends Root {}` with `class W implements Child` roots
+// `W.execute` at `Root.execute`, which `Child`'s own member list does not hold.
+// Static members and constructors are skipped for the same reason the direct
+// scan skips them — neither participates in a member relation.
+func inheritedMemberForProperty(
+  checker *shimchecker.Checker,
+  property *shimast.Symbol,
+) *shimast.Node {
+  if checker == nil || property == nil {
+    return nil
+  }
+  for _, root := range checker.GetRootSymbols(property) {
+    if root == nil {
+      continue
+    }
+    for _, declaration := range root.Declarations {
+      if declaration == nil ||
+        shimast.GetCombinedModifierFlags(declaration)&shimast.ModifierFlagsStatic != 0 ||
+        declaration.Kind == shimast.KindConstructor {
+        continue
+      }
+      return declaration
+    }
+  }
+  return nil
+}
+
+// directMemberForProperty maps an instantiated or transient checker property
+// back to the declaration the named base type itself owns. It answers nothing
+// for a property the base only inherits, which is what
+// inheritedMemberForProperty above then resolves.
+func directMemberForProperty(
+  checker *shimchecker.Checker,
+  property *shimast.Symbol,
+  members []*shimast.Node,
+) *shimast.Node {
+  for _, member := range members {
+    symbol := member.Symbol()
+    if symbol == nil || symbol.Name == "" ||
+      shimast.GetCombinedModifierFlags(member)&shimast.ModifierFlagsStatic != 0 ||
+      member.Kind == shimast.KindConstructor {
+      continue
+    }
+    if propertyRootsAt(checker, property, symbol) {
+      return member
+    }
+  }
+  return nil
+}
+
+func propertyRootsAt(checker *shimchecker.Checker, property, declaration *shimast.Symbol) bool {
+  if checker == nil || property == nil || declaration == nil {
+    return false
+  }
+  for _, root := range checker.GetRootSymbols(property) {
+    if root == declaration {
+      return true
     }
   }
+  return false
+}
+
+// graphMemberNodeID returns the existing graph node for a class or interface
+// member. It never materializes a new endpoint: member relations stay within
+// the same workspace-owned member surface Build already records.
+func graphMemberNodeID(g *Graph, member *shimast.Node) string {
+  if g == nil || member == nil || member.Symbol() == nil {
+    return ""
+  }
+  kind := NodeKind("")
+  switch {
+  case isMethodMember(member.Kind):
+    kind = NodeMethod
+  case isPropertyMember(member.Kind):
+    kind = NodeVariable
+  default:
+    return ""
+  }
+  file := shimast.GetSourceFileOfNode(member)
+  name := methodName(member.Symbol())
+  if file == nil || name == "" {
+    return ""
+  }
+  id := nodeID(file.FileName(), name, kind)
+  stored, ok := g.Nodes[id]
+  if !ok {
+    return ""
+  }
+  for _, declaration := range member.Symbol().Declarations {
+    declarationFile := shimast.GetSourceFileOfNode(declaration)
+    if declarationFile != nil && declarationFile.FileName() == stored.File &&
+      declaration.Pos() == stored.Pos && declaration.End() == stored.End {
+      return id
+    }
+  }
+  return ""
 }
 
 // collectCalls records a value-call edge from each declaration to every function,

package/internal/graph/enum_members_carry_their_names_on_the_enum_node_test.go

@@ -0,0 +1,131 @@
+package graph
+
+import (
+  "path/filepath"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestEnumMembersCarryTheirNamesOnTheEnumNode verifies that an enum records the
+// name and value of each member on its own node, and that nothing else does.
+//
+// The enum's node was always in the graph and had nothing in it (#738). Its
+// signature stops at the `{`, its members are not nodes, so the outline a class
+// gets is empty for an enum — and #732 gave it only values. The code writes
+// `Colors.Red`, never `"red"`, so a caller that had already named the enum
+// still opened the file for the one fact it came for.
+//
+// The names ride on the enum rather than on member nodes on purpose. A member
+// node would be indexing what `grep -rn "Colors.Red"` answers exactly, and it
+// would put leaves into tour flows to do it. Filling in a node the graph holds
+// is indexing; minting nodes to carry detail is not.
+//
+//  1. Compile a fixture with a string enum, an implicitly numbered one, and a
+//     class beside them.
+//  2. Build the graph.
+//  3. Assert each enum node carries its members name-and-value, that no member
+//     became a node, and that a class node carries none of this.
+func TestEnumMembersCarryTheirNamesOnTheEnumNode(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), `export enum Colors {
+  Red = 'red',
+  Green = 'green',
+}
+
+export enum Implicit {
+  First,
+  Second,
+}
+
+// Two members, one value: a type folds these together, a declaration does not.
+export enum Dup {
+  A = 'x',
+  B = 'x',
+  C = 'y',
+}
+
+export class Cls {
+  public value = 1;
+}
+`)
+
+  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() }()
+
+  graph := Build(prog)
+  path := sourceFile(t, prog, "main.ts").FileName()
+
+  colors, ok := graph.Nodes[nodeID(path, "Colors", NodeEnum)]
+  if !ok {
+    t.Fatalf("missing enum node; nodes: %v", nodeIDSet(graph))
+  }
+  want := []EnumMember{{Name: "Red", Value: `"red"`}, {Name: "Green", Value: `"green"`}}
+  if len(colors.EnumMembers) != len(want) {
+    t.Fatalf("Colors reported %v, want %v", colors.EnumMembers, want)
+  }
+  for i, member := range want {
+    if colors.EnumMembers[i] != member {
+      t.Fatalf("Colors member %d is %v, want %v", i, colors.EnumMembers[i], member)
+    }
+  }
+
+  // The values exist only in the checker here, so a scrape of the source could
+  // not produce this pairing.
+  implicit := graph.Nodes[nodeID(path, "Implicit", NodeEnum)]
+  if implicit == nil ||
+    len(implicit.EnumMembers) != 2 ||
+    implicit.EnumMembers[0] != (EnumMember{Name: "First", Value: "0"}) ||
+    implicit.EnumMembers[1] != (EnumMember{Name: "Second", Value: "1"}) {
+    t.Fatalf("implicitly numbered enum did not pair its members: %v", implicit.EnumMembers)
+  }
+
+  // Two members carrying one value. The declared type folds them into a single
+  // constituent — a type is a set — so reading the list off the type reports A
+  // and C and drops B, silently, which is #732's defect from #732's instinct:
+  // taking a declaration fact from a type. The list is the declaration's.
+  dup := graph.Nodes[nodeID(path, "Dup", NodeEnum)]
+  if dup == nil {
+    t.Fatalf("missing Dup; nodes: %v", nodeIDSet(graph))
+  }
+  if names := memberNames(dup.EnumMembers); len(names) != 3 ||
+    names[0] != "A" || names[1] != "B" || names[2] != "C" {
+    t.Fatalf("a member sharing another's value was dropped: %v", names)
+  }
+  // And the value set is right to say `"x"` once: two members, two names, but
+  // the values they admit really are two.
+  if len(dup.Literals) != 2 {
+    t.Fatalf("the value set should hold each distinct value once: %v", dup.Literals)
+  }
+
+  // The line this fix holds: the members are facts on the enum, not nodes of
+  // their own. A node per member would index what grep already answers.
+  for id := range graph.Nodes {
+    if id == nodeID(path, "Colors.Red", NodeVariable) ||
+      id == nodeID(path, "Red", NodeVariable) {
+      t.Fatalf("an enum member became a node (%s); it is a fact on the enum", id)
+    }
+  }
+
+  // The negative twin: this rides on enums only. A class's fields are member
+  // nodes and its outline comes from those.
+  if cls := graph.Nodes[nodeID(path, "Cls", NodeClass)]; cls == nil ||
+    len(cls.EnumMembers) != 0 {
+    t.Fatalf("a class node carried enum members: %v", cls)
+  }
+}
+
+func memberNames(members []EnumMember) []string {
+  out := make([]string, 0, len(members))
+  for _, member := range members {
+    out = append(out, member.Name)
+  }
+  return out
+}

package/internal/graph/graph.go

@@ -1,6 +1,8 @@
 package graph
 
 import (
+  "strings"
+
   shimast "github.com/microsoft/typescript-go/shim/ast"
 )
 
@@ -58,16 +60,82 @@ type Node struct {
   // the declaration's combined modifier flags during the build pass and emitted
   // for projections that filter on visibility and shape.
   Modifiers []string
+  // Literals is the complete value set of a type alias or enum whose declared
+  // type the checker resolved to literals, each rendered in TypeScript source
+  // form ("a", 1, true, null). It is set only when every constituent is
+  // enumerable, so a present list is the whole type and never a sample of it;
+  // a union that mixes in `string`, a type parameter, or a computed enum member
+  // has no complete answer and gets none.
+  //
+  // It is a checker fact because nothing else is sound. The value set was read
+  // off the declaration's source text for a while, which made the answer a
+  // function of line wrapping rather than of the type: a union written one
+  // member per line reported the members that fit in the snippet, an enum
+  // written across lines reported nothing at all, and `type I = Kind | 'f'`
+  // reported `'f'` while the members reaching it through `Kind` vanished (#732).
+  // The checker has already resolved every one of them, indirection included.
+  Literals []string
+  // EnumMembers is what an enum declares, in checker order: the name a caller
+  // writes and the value it carries. Empty for every other kind.
+  //
+  // The enum's node was always here and had nothing in it. `literals` says what
+  // values the enum admits, which answers a serializer; the code says
+  // `Colors.Red`, so a caller that had already named the enum still opened the
+  // file to learn what to type (#738). The members are not nodes of their own —
+  // `Colors.Red` is a literal string a grep finds exactly, and minting a node
+  // per member would grow the graph and put leaves into tour flows to index
+  // what grep already does. This fills in the node that exists instead.
+  EnumMembers []EnumMember
+  // ObjectMembers is the direct, statically named outline of an object literal
+  // assigned to this variable. It is captured from the compiler AST, in source
+  // order, so comments and lexical trivia cannot change member identity. The
+  // positions point into the same Program-owned source snapshot NewDump uses to
+  // render the compact signature and line carried on the wire.
+  ObjectMembers []ObjectMember
   // Pos and End bound the declaration in its source file (byte offsets). They
   // are for display, never identity, so an edit that shifts them does not re-key
   // the node.
-  Pos                int
-  End                int
+  Pos int
+  End int
+  // SignatureEnd bounds the declaration head — everything up to where the body
+  // opens. A consumer that guessed the boundary by scanning physical lines both
+  // leaked implementation text when a declaration shared its line with its body
+  // and stopped early when the head itself contained a brace, because a line is
+  // not a declaration boundary and a brace is not always a body. The compiler
+  // knows where the body starts, so it says so here. Zero when the declaration
+  // has no body to bound, in which case the whole declaration is the head.
+  SignatureEnd       int
   ImplementationFile string
   ImplementationPos  int
   ImplementationEnd  int
 }
 
+// EnumMember is one member of an enum: the name a caller writes and the value
+// it carries, in TypeScript source form. Value is empty when the checker could
+// not fold the member's initializer to a constant.
+type EnumMember struct {
+  Name  string
+  Value string
+}
+
+// ObjectMember is one direct, statically named property, method, or accessor of
+// an object-literal variable. A spread has no declaration name of its own and a
+// dynamic computed key cannot be named soundly, so neither fabricates a member.
+type ObjectMember struct {
+  Name string
+  Kind NodeKind
+  Pos  int
+  End  int
+  // SignatureEnd is the AST boundary before a nested value body. When the
+  // boundary lands at an opening token's full start, SignatureTokenLen says how
+  // many source bytes belong to the outline (`{`, `[`, or `class`). A true
+  // SignatureBoundary permits whitespace-normalizing a multiline declaration
+  // through that safe endpoint; otherwise the outline stops at its first line.
+  SignatureEnd      int
+  SignatureBoundary bool
+  SignatureTokenLen int
+}
+
 // EdgeKind classifies a relationship between two nodes.
 type EdgeKind string
 
@@ -75,6 +143,13 @@ const (
   // EdgeHeritage is an `extends` / `implements` relationship from a class or
   // interface to a base it derives from.
   EdgeHeritage EdgeKind = "heritage"
+  // EdgeMemberRelation is a checker-verified relationship from a directly
+  // declared member to the directly declared base member it implements or
+  // overrides. Origin is "implements" or "overrides" and becomes the wire
+  // kind. Keeping this separate from EdgeHeritage prevents a member fact from
+  // being confused with the syntactic container clause that led the checker to
+  // compare the two types.
+  EdgeMemberRelation EdgeKind = "member-relation"
   // EdgeValueCall is a runtime use from one declaration of the function, method,
   // or constructor it invokes: a call, a `new T()`, a `<Component/>` JSX use, or
   // a tagged-template tag. Uses of a dependency's method are not modeled (the
@@ -108,7 +183,8 @@ type Edge struct {
   // (calls / instantiates / renders, extends / implements) without the
   // MCP-facing model losing the distinction. It is "" for kinds that need no
   // split (type-ref, value-access). For EdgeValueCall it is "call", "new",
-  // "jsx", or "tagged"; for EdgeHeritage it is "extends" or "implements".
+  // "jsx", or "tagged"; for EdgeHeritage it is "extends" or "implements";
+  // for EdgeMemberRelation it is "implements" or "overrides".
   Origin string
   Pos    int
   End    int
@@ -148,7 +224,103 @@ type edgeKey struct {
 }
 
 // nodeID builds the position-invariant identity for a symbol named name,
-// declared as kind in the source file at path.
+// declared as kind in the source file at path. The visible grammar remains
+// path#name:kind, but path and name quote a literal backslash and hash so a
+// consumer never has to guess which hash separates the two components.
 func nodeID(path string, name string, kind NodeKind) string {
-  return path + "#" + name + ":" + string(kind)
+  return escapeNodeIDPart(path) + "#" + escapeNodeIDPart(name) + ":" + string(kind)
+}
+
+// nodeIDParts are the structured facts carried by a symbol id. File nodes are
+// raw paths rather than symbol ids, so parseNodeID deliberately rejects them.
+type nodeIDParts struct {
+  path string
+  name string
+  kind NodeKind
+}
+
+// parseNodeID recovers the structured path, name, and kind from an id emitted
+// by nodeID. It also accepts older ids whose ordinary components were not
+// escaped, so a newer reader can still consume a pre-codec dump.
+func parseNodeID(id string) (nodeIDParts, bool) {
+  hash := nodeIDHash(id)
+  if hash < 0 {
+    return nodeIDParts{}, false
+  }
+  tail := id[hash+1:]
+  colon := strings.LastIndex(tail, ":")
+  if colon <= 0 || colon == len(tail)-1 {
+    return nodeIDParts{}, false
+  }
+  return nodeIDParts{
+    path: unescapeNodeIDPart(id[:hash]),
+    name: unescapeNodeIDPart(tail[:colon]),
+    kind: NodeKind(tail[colon+1:]),
+  }, true
+}
+
+// nodeFile recovers the raw source path embedded in a symbol id. An id without
+// a symbol component is a file id, and therefore has no node-file component.
+func nodeFile(id string) string {
+  parts, ok := parseNodeID(id)
+  if !ok {
+    return ""
+  }
+  return parts.path
+}
+
+// NodeFile is the graph-symbol provider's shared view of the node-id grammar.
+// Keeping the parser here prevents its LSP path comparison from drifting from
+// the dump producer's edge-evidence lookup.
+func NodeFile(id string) string {
+  return nodeFile(id)
+}
+
+func escapeNodeIDPart(value string) string {
+  value = strings.ReplaceAll(value, "\\", "\\\\")
+  return strings.ReplaceAll(value, "#", "\\#")
+}
+
+func unescapeNodeIDPart(value string) string {
+  var out strings.Builder
+  out.Grow(len(value))
+  for i := 0; i < len(value); i++ {
+    if value[i] == '\\' && i+1 < len(value) {
+      next := value[i+1]
+      if next == '#' || (next == '\\' && !legacyUNCStart(value, i)) {
+        i++
+      }
+    }
+    out.WriteByte(value[i])
+  }
+  return out.String()
+}
+
+// legacyUNCStart distinguishes an older raw UNC path (\\server) from a new
+// codec spelling (\\\\server). The former predates backslash escaping and must
+// remain readable by a current consumer.
+func legacyUNCStart(value string, index int) bool {
+  return index == 0 && len(value) > 2 && value[2] != '\\' && value[2] != '#'
+}
+
+func nodeIDHash(id string) int {
+  for i := 0; i < len(id); i++ {
+    if id[i] != '#' {
+      continue
+    }
+    if i == 0 || id[i-1] != '\\' || escapedBackslash(id, i-1) {
+      return i
+    }
+  }
+  return -1
+}
+
+// escapedBackslash reports whether slash is itself escaped by the run before
+// it. Only an odd run quotes the following hash.
+func escapedBackslash(id string, slash int) bool {
+  count := 0
+  for i := slash; i >= 0 && id[i] == '\\'; i-- {
+    count++
+  }
+  return count%2 == 0
 }