@ttsc/wasm 0.30.4 → 0.31.1

package/shim-vendor/shim/ast/parent.go

@@ -2,37 +2,53 @@ package ast
 
 import innerast "github.com/microsoft/typescript-go/internal/ast"
 
-// SetParentInChildren recursively sets each descendant node's Parent pointer to
-// its containing node.
+// SetParentInChildren sets Parent pointers along the compiler's ForEachChild
+// traversal to each child's containing node.
 //
 // A transform that splices freshly built (synthetic) nodes onto a SourceFile
-// must call this before emit, because the passes that then walk the spliced tree
-// dereference Parent and would hit nil on a synthetic node. The printer is the
-// example that holds up: getContainingNodeArray reads node.Parent unguarded for
-// a parameter, template span, decorator, and heritage clause.
+// must establish valid parent relationships before a pass that relies on them;
+// this overwrite operation is one way to do so. The printer's
+// getContainingNodeArray first permits a nil parent, then uses parent-kind and
+// payload relationships to select a containing list. A wrong existing parent
+// can therefore select the wrong list or fail a payload assertion.
 //
-// Two earlier examples were dropped rather than the rule. The emit resolver's
-// reference marking no longer walks the spliced tree at all in ttsc's plugin
-// emit lane, which builds the builtin chain from the parse tree (see
-// driver.EmitWithPluginTransformers). The module transform's own Parent reads
-// carry upstream //nolint:customlint notes saying they deliberately inspect
-// parse-tree parents.
+// This overwrites existing parent links. Use SetParentInChildrenUnset when a
+// transform reuses parse-tree children whose original ancestry must survive.
+// The root must be nonnil with valid compiler payloads and an acyclic child
+// tree. Callers must own the parent mutations without concurrent tree access.
+//
+// @evidence contracts/common.md#principled-implementation Recursive upstream child traversal assigns each child's immediate containing node, matching the AST parent relation for an acyclic tree.
+// @evidence contracts/common.md#clear-and-simple-design The wrapper exposes upstream's overwrite operation separately from the preserve-existing-parent operation, so callers choose ownership explicitly.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The only mutation is the requested AST parent wiring through the compiler's own traversal API; it does not replace foreign methods or globals.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the overwrite effect, emit motivation, alternative for reused parse nodes, and nonnil acyclic-tree premise with separated paragraphs.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The shim controls no independent traversal-state lifetime. Upstream checks a setter closure out of sync.Pool and defers returning it; normal traversal restores its parent reference. The pool has no numeric cap, and an invalid-tree panic can leave captured parent state until the pool entry is discarded. Mutated Parent links remain owned by the caller's tree.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The shim chooses no independent parent-traversal algorithm. Upstream visits V traversed nodes with O(V) work and up to O(H) stack for child depth H, without collecting all descendants; caller graphs must be valid trees.
+// @evidence contracts/performance.md#reuse-equivalent-work Upstream shares reusable setter closures through sync.Pool, checking one out for a traversal and returning it with defer. Normal completion restores the mutable parent cursor before reuse; this pools traversal machinery, not a cached result that could skip required parent mutations.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation SetParentInChildren computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func SetParentInChildren(node *Node) {
   innerast.SetParentInChildren(node)
 }
 
-// SetParentInChildrenUnset sets Parent only on nodes that don't already have
-// one, recursing through the whole tree. Unlike SetParentInChildren it does NOT
+// SetParentInChildrenUnset sets Parent only on visited children that do not
+// already have one, using the compiler's ForEachChild traversal. Unlike
+// SetParentInChildren it does not
 // overwrite the parent of original parse-tree nodes that a transform reused
-// inside a rebuilt SourceFile — overwriting those (e.g. an `export namespace`
-// kept verbatim while sibling statements were rewritten) makes tsgo's
-// runtime-syntax/printer mis-resolve the declaration and drop it from emit.
-// Only freshly built (synthetic) nodes need a parent wired, and those start nil.
+// inside a rebuilt SourceFile. Changing preserved ancestry can change how
+// downstream parent-sensitive passes interpret those declarations. Nil parent
+// links are wired regardless of whether a node is marked synthetic.
+//
+// Supply a nonnil root with valid compiler payloads and an acyclic child tree.
+// Existing links remain authoritative even if they point outside the rebuilt
+// tree; callers must own mutations without concurrent tree access.
 //
-// This is the form ttsc's plugin emit lane calls. How much it currently carries
-// is unproven: stubbing the call out leaves the whole driver suite green, which
-// measures the suite's coverage of parent-dependent emit rather than the hazard.
-// Keep it for the reason above, not on the strength of a failing test.
+// @evidence contracts/common.md#principled-implementation Every traversed child receives its containing node only when Parent is nil, preserving reused parse-tree ancestry while wiring synthetic descendants in an acyclic tree.
+// @evidence contracts/common.md#clear-and-simple-design A single recursive child traversal owns the nil-only assignment; the overwrite variant remains a separate explicit operation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The nil check is the requested preservation policy, not synthetic-flag inference or a fixture exception; no foreign method is replaced and existing parents are preserved deliberately.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains why existing parents survive, the synthetic-node case, and the nonnil acyclic-tree premise without relying on test history.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This traversal acquires no native handle, task or independently retained cache. Assigned and preserved Parent references remain in the caller-owned tree and can keep ancestor objects reachable, including ancestors outside the rebuilt root; tree owners control that lifetime.
+// @evidence contracts/performance.md#efficient-algorithms One recursive ForEachChild traversal visits V nodes and tests each child parent once, costing O(V) time and O(H) stack for depth H. Already-parented subtrees are still traversed because their deeper children can have nil parents; no full descendant collection is allocated.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The traversal coordinates no cached result or in-flight work. Existing nonnil Parent values are preserved as caller-authoritative state, while descendants still require inspection for missing links.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation SetParentInChildrenUnset computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func SetParentInChildrenUnset(node *Node) {
   node.ForEachChild(func(child *Node) bool {
     if child.Parent == nil {

package/shim-vendor/shim/ast/safe_text.go

@@ -1,14 +1,13 @@
 // gen_shims:hand-maintained
 //
-// Total-function replacement for upstream `(*Node).Text()`.
+// Text accessor for valid compiler nodes beyond upstream `(*Node).Text()`.
 //
-// Upstream panics for any Kind missing from its switch — most notably
+// Upstream panics for any Kind missing from its switch, most notably
 // KindQualifiedName, which surfaces in JSDoc parameter names (`@param
 // obj.field`) and dotted entity references. NodeText handles
-// QualifiedName by recursing on the left subtree and joining with the
-// right identifier, and falls back to the source-text slice for any
-// other Kind so downstream code can treat the helper as a total
-// function over *Node instead of guarding each call site.
+// QualifiedName by collecting the left chain and joining nonempty components,
+// and falls back to the checked source-text slice for other kinds. Payloads
+// must match their kinds and parent/qualified-name chains must terminate.
 
 package ast
 
@@ -22,6 +21,21 @@ import (
 // upstream `(*Node).Text()` where upstream has an arm, adds a
 // QualifiedName arm that joins `left.right`, and falls back to the
 // node's source slice for any other Kind. Returns "" for nil.
+//
+// A node's payload must match its Kind, present qualified-name right nodes must
+// be valid text-bearing names, and parent/qualified-name chains must terminate.
+// Unsupported kinds without a valid containing source range return "" instead
+// of synthesizing spelling. This is not a total function for malformed cycles
+// or mismatched payloads.
+//
+// @evidence contracts/common.md#principled-implementation Known text-bearing kinds use their upstream payload accessor, qualified names concatenate their identifier components, and other kinds use checked source byte ranges; nodes must have payloads matching their Kind.
+// @evidence contracts/common.md#clear-and-simple-design One kind dispatch separates semantic token text from qualified-name composition and the private source-range fallback, keeping the safety policy local.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Kind-specific cases reflect actual AST representations missing from upstream Text, and the range fallback does not patch that foreign method or special-case consumers.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes token text from source spelling, documents nil and unavailable ranges, and states the payload premise using separated body and tag sections.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Qualified-name assembly uses temporary O(H) component references and transfers the assembled string to the caller; no handle or task is acquired. Direct payload and source-slice results may keep their backing text reachable, including a whole source string for a small slice. Caller references determine that lifetime; no independent cache or retained-byte cap is owned here.
+// @evidence contracts/performance.md#efficient-algorithms A qualified chain of H links is collected once and its B output bytes are appended once with a builder, costing O(H+B) time and O(H+B) temporary/output space instead of repeatedly copying growing prefixes. Other valid kinds delegate text access; source fallback walks P parent links and trims W range bytes in O(P+W). Upstream composed text such as JSX namespace names retains its own byte-copy cost.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This text query coordinates no completed-result cache or in-flight work; compiler-tree owners establish validity when sharing node spelling and source ranges across calls.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation NodeText computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func NodeText(n *Node) string {
   if n == nil {
     return ""
@@ -45,33 +59,41 @@ func NodeText(n *Node) string {
     innerast.KindMetaProperty:
     return n.Text()
   case KindQualifiedName:
-    qn := n.AsQualifiedName()
-    if qn == nil {
-      return ""
+    var parts []string
+    for n != nil && n.Kind == KindQualifiedName {
+      qn := n.AsQualifiedName()
+      if qn == nil {
+        n = nil
+        break
+      }
+      if qn.Right != nil {
+        if text := qn.Right.Text(); text != "" {
+          parts = append(parts, text)
+        }
+      }
+      n = qn.Left
     }
-    left := NodeText(qn.Left)
-    right := ""
-    if qn.Right != nil {
-      right = qn.Right.Text()
-    }
-    switch {
-    case left == "" && right == "":
-      return ""
-    case left == "":
-      return right
-    case right == "":
+    left := NodeText(n)
+    if len(parts) == 0 {
       return left
-    default:
-      return left + "." + right
     }
+    var result strings.Builder
+    result.WriteString(left)
+    for i := len(parts) - 1; i >= 0; i-- {
+      if result.Len() != 0 {
+        result.WriteByte('.')
+      }
+      result.WriteString(parts[i])
+    }
+    return result.String()
   }
   return nodeSourceText(n)
 }
 
-// nodeSourceText returns the verbatim source slice covered by the node's
-// position range, trimmed of surrounding whitespace. Same byte range
-// scanner.GetTextOfNode would read; safe for any Kind because it does
-// not inspect per-Kind data fields.
+// nodeSourceText checks the containing source range and trims surrounding
+// whitespace. It does not perform scanner.GetTextOfNode's SkipTrivia step, so
+// leading comments may remain. Kind-specific payloads are not inspected here;
+// source ownership still requires a terminating, valid parent chain.
 func nodeSourceText(n *innerast.Node) string {
   file := innerast.GetSourceFileOfNode(n)
   if file == nil {