ttsc 0.16.3 → 0.16.5

package/internal/graph/decorators.go

@@ -0,0 +1,122 @@
+package graph
+
+import (
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// DecoratorArgument is one argument written on a decorator. Literal holds the
+// statically-resolved value when the argument is a string or boolean literal
+// and is nil otherwise; Text is always the argument's printable source.
+type DecoratorArgument struct {
+  Text    string
+  Literal any
+}
+
+// Decorator is a decorator as written on a workspace declaration, captured so a
+// consumer can interpret a decorator convention (`@Controller('users')`,
+// `@Get(':id')`) without re-parsing source. Target is the id of the graph node
+// the decorator is applied to; Pos/End bound the decorator for evidence.
+type Decorator struct {
+  Target    string
+  Name      string
+  Arguments []DecoratorArgument
+  File      string
+  Pos       int
+  End       int
+}
+
+// collectDecorators records the decorators on each class plus its methods and
+// properties, descending into namespace bodies. It is syntactic — a decorator's
+// name and literal arguments are read straight from the AST — because a consumer
+// keys on the written convention name, not the resolved decorator symbol.
+func (g *Graph) collectDecorators(path string, statements []*shimast.Node) {
+  for _, statement := range statements {
+    switch statement.Kind {
+    case shimast.KindClassDeclaration:
+      if id := topLevelID(path, statement, NodeClass); id != "" {
+        g.nodeDecorators(id, path, statement)
+      }
+      g.memberDecorators(path, statement)
+    case shimast.KindModuleDeclaration:
+      g.collectDecorators(path, moduleStatements(statement))
+    }
+  }
+}
+
+// memberDecorators records the decorators on the methods and properties of a
+// class declaration, attributed to their member nodes.
+func (g *Graph) memberDecorators(path string, statement *shimast.Node) {
+  for _, member := range classMembers(statement) {
+    name := methodName(member.Symbol())
+    if name == "" {
+      continue
+    }
+    switch {
+    case isMethodMember(member.Kind):
+      g.nodeDecorators(nodeID(path, name, NodeMethod), path, member)
+    case isPropertyMember(member.Kind):
+      g.nodeDecorators(nodeID(path, name, NodeVariable), path, member)
+    }
+  }
+}
+
+// nodeDecorators appends a Decorator fact for every decorator on node, targeting
+// the graph node identified by targetID.
+func (g *Graph) nodeDecorators(targetID, path string, node *shimast.Node) {
+  for _, dec := range node.Decorators() {
+    fact := decoratorFact(dec)
+    if fact == nil {
+      continue
+    }
+    fact.Target = targetID
+    fact.File = path
+    g.Decorators = append(g.Decorators, fact)
+  }
+}
+
+// decoratorFact reads a decorator node into a Decorator, or nil when its
+// expression has no recoverable name. `@Get(':id')` yields name "Get" with one
+// literal argument; a bare `@Injectable` yields name "Injectable" and no
+// arguments.
+func decoratorFact(dec *shimast.Node) *Decorator {
+  decl := dec.AsDecorator()
+  if decl == nil || decl.Expression == nil {
+    return nil
+  }
+  fact := &Decorator{Pos: dec.Pos(), End: dec.End()}
+  expr := decl.Expression
+  if expr.Kind == shimast.KindCallExpression {
+    call := expr.AsCallExpression()
+    if call == nil || call.Expression == nil {
+      return nil
+    }
+    fact.Name = shimast.NodeText(call.Expression)
+    if call.Arguments != nil {
+      for _, arg := range call.Arguments.Nodes {
+        fact.Arguments = append(fact.Arguments, decoratorArg(arg))
+      }
+    }
+  } else {
+    fact.Name = shimast.NodeText(expr)
+  }
+  if fact.Name == "" {
+    return nil
+  }
+  return fact
+}
+
+// decoratorArg captures one decorator argument. Only string and boolean literals
+// resolve to a Literal — the values a consumer can use directly — so a
+// non-literal argument keeps its source Text with a nil Literal.
+func decoratorArg(arg *shimast.Node) DecoratorArgument {
+  out := DecoratorArgument{Text: shimast.NodeText(arg)}
+  switch arg.Kind {
+  case shimast.KindStringLiteral, shimast.KindNoSubstitutionTemplateLiteral:
+    out.Literal = arg.Text()
+  case shimast.KindTrueKeyword:
+    out.Literal = true
+  case shimast.KindFalseKeyword:
+    out.Literal = false
+  }
+  return out
+}

package/internal/graph/decorators_capture_name_and_literal_arguments_test.go

@@ -0,0 +1,98 @@
+package graph
+
+import (
+  "path/filepath"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestDecoratorsCaptureNameAndLiteralArguments verifies that collectDecorators
+// records each decorator on a class and on its methods with the convention name
+// and the statically-resolved literal arguments, attributed to the decorated
+// node — the facts a consumer reads to interpret a decorator convention without
+// re-parsing source.
+//
+// A convention's value lives in the decorator's literal argument, so the test
+// pins both axes a consumer depends on: the decorator name (`Controller`,
+// `Get`) and the unquoted literal value (`users`, `:id`), each on the right
+// target node. A bare method with no decorator is the negative twin: it must
+// contribute no decorator fact.
+//
+//  1. Compile a controller-shaped fixture with @Controller("users") on the class
+//     and @Get(":id") on one method, plus an undecorated method, using local
+//     decorator factories so the program type-checks with no dependency.
+//  2. Build the graph.
+//  3. Assert a Decorator targets the class with name "Controller" / literal
+//     "users", one targets the method with name "Get" / literal ":id", and the
+//     undecorated method has no fact.
+func TestDecoratorsCaptureNameAndLiteralArguments(t *testing.T) {
+  root := t.TempDir()
+  writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
+  writeFile(t, filepath.Join(root, "src", "main.ts"), `function Controller(prefix: string): any {
+  void prefix;
+  return () => {};
+}
+function Get(path: string): any {
+  void path;
+  return () => {};
+}
+@Controller("users")
+export class UsersController {
+  @Get(":id")
+  find(): void {}
+  plain(): 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() }()
+
+  graph := Build(prog)
+  path := sourceFile(t, prog, "main.ts").FileName()
+
+  controller := nodeID(path, "UsersController", NodeClass)
+  find := nodeID(path, "UsersController.find", NodeMethod)
+  plain := nodeID(path, "UsersController.plain", NodeMethod)
+
+  classDec := findDecorator(graph, controller, "Controller")
+  if classDec == nil {
+    t.Fatalf("missing @Controller fact on the class; decorators: %v", graph.Decorators)
+  }
+  if len(classDec.Arguments) != 1 || classDec.Arguments[0].Literal != "users" {
+    t.Fatalf("@Controller args: want one literal \"users\", got %v", classDec.Arguments)
+  }
+
+  methodDec := findDecorator(graph, find, "Get")
+  if methodDec == nil {
+    t.Fatalf("missing @Get fact on UsersController.find; decorators: %v", graph.Decorators)
+  }
+  if len(methodDec.Arguments) != 1 || methodDec.Arguments[0].Literal != ":id" {
+    t.Fatalf("@Get args: want one literal \":id\", got %v", methodDec.Arguments)
+  }
+
+  // Negative twin: an undecorated method contributes no decorator fact, so a
+  // consumer sees no decorator on it.
+  for _, d := range graph.Decorators {
+    if d.Target == plain {
+      t.Fatalf("undecorated method UsersController.plain gained a decorator fact: %+v", d)
+    }
+  }
+}
+
+// findDecorator returns the first decorator fact targeting target with the given
+// name, or nil.
+func findDecorator(graph *Graph, target, name string) *Decorator {
+  for _, d := range graph.Decorators {
+    if d.Target == target && d.Name == name {
+      return d
+    }
+  }
+  return nil
+}

package/internal/graph/diagnostics.go

@@ -0,0 +1,23 @@
+package graph
+
+import "github.com/samchon/ttsc/packages/ttsc/driver"
+
+// FileDiagnostics returns the resident program's compiler diagnostics for the
+// source file at path, in the same code and location tsgo reports. Because the
+// graph rides the already-open Program, this is one Program.Diagnostics() call
+// over the warm checker, not a second compile.
+//
+// This is the compiler-only slice: it carries the TypeScript semantic
+// diagnostics, not @ttsc/lint or transform-plugin findings. The MCP server fuses
+// those onto the graph separately, through diagnostic providers the launcher
+// feeds (see mcp.DiagnosticProvider). This helper and its tests pin the
+// compiler-diagnostic conversion (code, column, message) on its own.
+func FileDiagnostics(prog *driver.Program, path string) []driver.Diagnostic {
+  out := make([]driver.Diagnostic, 0)
+  for _, diagnostic := range prog.Diagnostics() {
+    if diagnostic.File == path {
+      out = append(out, diagnostic)
+    }
+  }
+  return out
+}

package/internal/graph/dump.go

@@ -0,0 +1,390 @@
+package graph
+
+import (
+  "encoding/json"
+  "path/filepath"
+  "sort"
+  "strings"
+)
+
+// dump.go projects a built graph onto the JSON wire contract `ttscgraph dump`
+// prints — the IGraphDump shape the @ttsc/graph engine loads (and the 3D viewer
+// reduces). The internal Node/Edge model stays narrow (so the resident MCP path
+// is untouched); the richer schema is produced here:
+//
+//   - internal node kinds map straight through (NodeTypeAlias is already "type");
+//   - one EdgeValueCall splits by Origin into "calls" / "instantiates" /
+//     "renders", and EdgeHeritage into "extends" / "implements";
+//   - every edge is tagged checker-resolved / high (the graph's whole contract);
+//   - byte spans become 1-based line/col Evidence, with a short excerpt on edges;
+//   - decorator facts ride on their target node;
+//   - file paths are project-relative and the output is sorted, so the dump is
+//     deterministic and diffable.
+//
+// Structural derivations the schema also defines (file nodes, contains/exports
+// edges) are left to the TypeScript loader, which has the node set in hand and
+// is where the redesign keeps that logic.
+
+// DumpEvidence is a 1-based source span grounding a node declaration or an edge
+// expression. It is display/expansion only, never identity.
+type DumpEvidence struct {
+  File      string `json:"file"`
+  StartLine int    `json:"startLine"`
+  StartCol  int    `json:"startCol,omitempty"`
+  EndLine   int    `json:"endLine,omitempty"`
+  EndCol    int    `json:"endCol,omitempty"`
+  Text      string `json:"text,omitempty"`
+}
+
+// DumpDecoratorArgument is one decorator argument; Literal is set only for a
+// statically-resolved string or boolean literal.
+type DumpDecoratorArgument struct {
+  Text    string `json:"text"`
+  Literal any    `json:"literal,omitempty"`
+}
+
+// DumpDecorator is a decorator as written on a declaration, carried on its
+// target node for a consumer to interpret.
+type DumpDecorator struct {
+  Name      string                  `json:"name"`
+  Arguments []DumpDecoratorArgument `json:"arguments"`
+}
+
+// DumpNode is the wire shape of a graph node. Lowercase json keys are the
+// contract; the Go field names are not.
+type DumpNode struct {
+  ID            string          `json:"id"`
+  Kind          string          `json:"kind"`
+  Name          string          `json:"name"`
+  QualifiedName string          `json:"qualifiedName,omitempty"`
+  File          string          `json:"file"`
+  External      bool            `json:"external"`
+  Ignored       bool            `json:"ignored,omitempty"`
+  Exported      bool            `json:"exported,omitempty"`
+  Modifiers     []string        `json:"modifiers,omitempty"`
+  Evidence      *DumpEvidence   `json:"evidence,omitempty"`
+  Decorators    []DumpDecorator `json:"decorators,omitempty"`
+}
+
+// DumpEdge is the wire shape of a graph edge. Lowercase json keys are the
+// contract; the Go field names are not.
+type DumpEdge struct {
+  From     string        `json:"from"`
+  To       string        `json:"to"`
+  Kind     string        `json:"kind"`
+  Evidence *DumpEvidence `json:"evidence,omitempty"`
+}
+
+// Dump is the IGraphDump envelope: the project it was built for and the full
+// node and edge sets with none of the MCP response caps.
+type Dump struct {
+  Project  string     `json:"project"`
+  Tsconfig string     `json:"tsconfig"`
+  Nodes    []DumpNode `json:"nodes"`
+  Edges    []DumpEdge `json:"edges"`
+}
+
+// NewDump projects a built graph onto the export shape. project is the absolute
+// project root used to relativize file paths and node ids; ignored is the
+// git-ignored source set (nil for a non-git project); sources maps a source
+// file's path to its text so byte spans become line/col evidence (nil omits
+// evidence).
+func NewDump(g *Graph, project, tsconfig string, ignored map[string]bool, sources map[string]string) Dump {
+  ctx := newDumpContext(project, sources)
+
+  // Decorators ride on their target node; group by the internal node id before
+  // ids are relativized for output.
+  decByNode := make(map[string][]DumpDecorator, len(g.Decorators))
+  for _, d := range g.Decorators {
+    args := make([]DumpDecoratorArgument, 0, len(d.Arguments))
+    for _, a := range d.Arguments {
+      args = append(args, DumpDecoratorArgument{Text: a.Text, Literal: a.Literal})
+    }
+    decByNode[d.Target] = append(decByNode[d.Target], DumpDecorator{Name: d.Name, Arguments: args})
+  }
+
+  nodes := make([]DumpNode, 0, len(g.Nodes))
+  for _, n := range g.Nodes {
+    name, qualified := nodeNames(n)
+    nodes = append(nodes, DumpNode{
+      ID:            ctx.relID(n.ID),
+      Kind:          string(n.Kind),
+      Name:          name,
+      QualifiedName: qualified,
+      File:          ctx.rel(n.File),
+      External:      n.External,
+      Ignored:       ignored[n.File],
+      Exported:      n.Exported,
+      Modifiers:     n.Modifiers,
+      Evidence:      ctx.evidence(n.File, n.Pos, n.End, false),
+      Decorators:    decByNode[n.ID],
+    })
+  }
+  sort.Slice(nodes, func(i, j int) bool { return nodes[i].ID < nodes[j].ID })
+
+  edges := make([]DumpEdge, 0, len(g.Edges))
+  for _, e := range g.Edges {
+    edges = append(edges, DumpEdge{
+      From:     ctx.relID(e.From),
+      To:       ctx.relID(e.To),
+      Kind:     dumpEdgeKind(e),
+      Evidence: ctx.edgeEvidence(e),
+    })
+  }
+  sort.Slice(edges, func(i, j int) bool {
+    if edges[i].From != edges[j].From {
+      return edges[i].From < edges[j].From
+    }
+    if edges[i].To != edges[j].To {
+      return edges[i].To < edges[j].To
+    }
+    return edges[i].Kind < edges[j].Kind
+  })
+
+  return Dump{
+    Project:  project,
+    Tsconfig: tsconfig,
+    Nodes:    nodes,
+    Edges:    edges,
+  }
+}
+
+// MarshalDump serializes a built graph to the export JSON, indented when pretty.
+// See NewDump for the parameters.
+func MarshalDump(g *Graph, project, tsconfig string, ignored map[string]bool, sources map[string]string, pretty bool) ([]byte, error) {
+  d := NewDump(g, project, tsconfig, ignored, sources)
+  if pretty {
+    return json.MarshalIndent(d, "", "  ")
+  }
+  return json.Marshal(d)
+}
+
+// dumpEdgeKind maps an internal edge kind, refined by Edge.Origin, onto the
+// schema's finer relationship kind.
+func dumpEdgeKind(e *Edge) string {
+  return wireEdgeKind(e.Kind, e.Origin)
+}
+
+// wireEdgeKind maps an internal edge kind, refined by its origin, onto the
+// schema's finer relationship kind. It is the edge's emitted identity, so the
+// dedup keys on it: two uses of one target that differ only in a form mapping to
+// the same wire kind (a plain call and a tagged-template call, both `calls`)
+// collapse to one edge, while forms that mean distinct relationships (`calls` vs
+// `instantiates`, `extends` vs `implements`) are each kept.
+func wireEdgeKind(kind EdgeKind, origin string) string {
+  switch kind {
+  case EdgeValueCall:
+    switch origin {
+    case "new":
+      return "instantiates"
+    case "jsx":
+      return "renders"
+    default:
+      return "calls"
+    }
+  case EdgeValueAccess:
+    return "accesses"
+  case EdgeTypeRef:
+    return "type_ref"
+  case EdgeHeritage:
+    if origin == "extends" {
+      return "extends"
+    }
+    return "implements"
+  default:
+    return string(kind)
+  }
+}
+
+// nodeNames returns a node's simple name and, when it is owner-qualified, its
+// full qualified form for the wire. The simple name is the symbol's own name
+// recorded at build time, so a quoted member whose name contains a dot
+// (`"a.b"` → Name `C.a.b`) splits exactly; the qualified form is the full Name
+// when it differs from the simple name, and "" for a top-level declaration.
+// A node without a recorded simple name (a future virtual node) falls back to
+// the last dot-separated segment.
+func nodeNames(n *Node) (simple, qualified string) {
+  if n.Simple == "" {
+    if dot := strings.LastIndex(n.Name, "."); dot >= 0 {
+      return n.Name[dot+1:], n.Name
+    }
+    return n.Name, ""
+  }
+  if n.Simple == n.Name {
+    return n.Simple, ""
+  }
+  return n.Simple, n.Name
+}
+
+// dumpContext relativizes paths and turns byte spans into line/col evidence,
+// caching a per-file line index so a large file's many edges cost O(log n) each
+// instead of a re-scan.
+type dumpContext struct {
+  project string
+  sources map[string]string
+  lines   map[string]lineStarts
+}
+
+func newDumpContext(project string, sources map[string]string) *dumpContext {
+  return &dumpContext{
+    project: strings.TrimRight(filepath.ToSlash(project), "/"),
+    sources: sources,
+    lines:   map[string]lineStarts{},
+  }
+}
+
+// rel makes a source file path project-relative; an external path keeps its
+// node_modules-relative tail so a dependency leaf stays readable.
+func (c *dumpContext) rel(file string) string {
+  f := filepath.ToSlash(file)
+  if c.project != "" {
+    if f == c.project {
+      return ""
+    }
+    if strings.HasPrefix(f, c.project+"/") {
+      return f[len(c.project)+1:]
+    }
+  }
+  if i := strings.LastIndex(f, "/node_modules/"); i >= 0 {
+    return f[i+1:]
+  }
+  return f
+}
+
+// relID relativizes the path portion of a node id ("path#qualifiedName:kind").
+// An id with no path (a future virtual node) is returned unchanged.
+func (c *dumpContext) relID(id string) string {
+  hash := strings.Index(id, "#")
+  if hash < 0 {
+    return id
+  }
+  return c.rel(id[:hash]) + id[hash:]
+}
+
+// evidence builds the line/col span for a byte range in file, or nil when the
+// span is absent or no source is available. includeText attaches a one-line
+// excerpt (used for edge expressions, not declaration bodies).
+func (c *dumpContext) evidence(file string, pos, end int, includeText bool) *DumpEvidence {
+  if pos < 0 || c.sources == nil {
+    return nil
+  }
+  text, ok := c.sources[file]
+  if !ok {
+    return nil
+  }
+  ls := c.lines[file]
+  if ls == nil {
+    ls = newLineStarts(text)
+    c.lines[file] = ls
+  }
+  if pos > len(text) {
+    return nil
+  }
+  // Node.Pos() and an expression's Pos() are the full-start: they include the
+  // leading whitespace and doc comments before the token. Advance to the first
+  // code character so the line/column point at the declaration, not its banner
+  // or its indentation.
+  pos = firstCodeOffset(text, pos)
+  sl, sc := ls.at(pos)
+  ev := &DumpEvidence{File: c.rel(file), StartLine: sl, StartCol: sc}
+  if end > pos && end <= len(text) {
+    ev.EndLine, ev.EndCol = ls.at(end)
+    if includeText {
+      ev.Text = excerpt(text[pos:end])
+    }
+  }
+  return ev
+}
+
+// firstCodeOffset advances past leading trivia — whitespace, // line comments,
+// and /* */ block comments — from pos to the first code byte, or len(text) if
+// the rest is all trivia. It mirrors how a token's real start is found, so an
+// evidence span lands on the declaration rather than the comment above it.
+func firstCodeOffset(text string, pos int) int {
+  i := pos
+  for i < len(text) {
+    switch {
+    case text[i] == ' ' || text[i] == '\t' || text[i] == '\r' || text[i] == '\n':
+      i++
+    case text[i] == '/' && i+1 < len(text) && text[i+1] == '/':
+      i += 2
+      for i < len(text) && text[i] != '\n' {
+        i++
+      }
+    case text[i] == '/' && i+1 < len(text) && text[i+1] == '*':
+      i += 2
+      for i+1 < len(text) && !(text[i] == '*' && text[i+1] == '/') {
+        i++
+      }
+      if i+1 < len(text) {
+        i += 2
+      } else {
+        i = len(text)
+      }
+    default:
+      return i
+    }
+  }
+  return i
+}
+
+// edgeEvidence is the evidence for an edge's source expression, with a short
+// excerpt of the expression text.
+func (c *dumpContext) edgeEvidence(e *Edge) *DumpEvidence {
+  // The edge's span lives in the From node's file.
+  file := nodeFile(e.From)
+  if file == "" {
+    return nil
+  }
+  return c.evidence(file, e.Pos, e.End, true)
+}
+
+// nodeFile recovers the source file path embedded in a node id
+// ("path#qualifiedName:kind"); "" for an id without a path.
+func nodeFile(id string) string {
+  if hash := strings.Index(id, "#"); hash >= 0 {
+    return id[:hash]
+  }
+  return ""
+}
+
+// excerpt is a single-line, length-capped slice of source text for inline
+// evidence.
+func excerpt(s string) string {
+  s = strings.TrimSpace(s)
+  if i := strings.IndexByte(s, '\n'); i >= 0 {
+    s = s[:i]
+  }
+  if len(s) > 160 {
+    // Drop a trailing partial UTF-8 rune so the excerpt cannot end mid-character.
+    s = strings.TrimSpace(strings.ToValidUTF8(s[:160], "")) + "…"
+  }
+  return s
+}
+
+// lineStarts holds the byte offset of each line's start, so an offset maps to a
+// 1-based line/column by binary search.
+type lineStarts []int
+
+func newLineStarts(text string) lineStarts {
+  starts := make(lineStarts, 1, 1+strings.Count(text, "\n"))
+  starts[0] = 0
+  for i := 0; i < len(text); i++ {
+    if text[i] == '\n' {
+      starts = append(starts, i+1)
+    }
+  }
+  return starts
+}
+
+// at returns the 1-based line and column of a byte offset.
+func (ls lineStarts) at(offset int) (line, col int) {
+  if offset < 0 || len(ls) == 0 {
+    return 0, 0
+  }
+  i := sort.Search(len(ls), func(i int) bool { return ls[i] > offset }) - 1
+  if i < 0 {
+    i = 0
+  }
+  return i + 1, offset - ls[i] + 1
+}