@nestia/core 12.0.0 → 13.0.0

package/native/transform/node_transform.go

@@ -15,8 +15,7 @@ import (
 // runtime references resolve to namespace imports tsgo's module-transform
 // aliases), injects those imports, and normalizes the synthetic operator tokens
 // typia's programmers leave nil. A diagnostic is appended for any site whose
-// generation raises a (recovered) transform error, matching the legacy text
-// path's swallow-and-report behavior.
+// generation raises a (recovered) transform error.
 //
 // addDiagnostic receives one entry per failed site; the build command turns a
 // non-empty diagnostic slice into a non-zero exit.
@@ -97,8 +96,7 @@ func nestiaCoreNodeTransform(
 		result = nestiaCoreInjectImports(result, importer.ToStatements(), ec)
 		// The node path prints through tsgo's printer, which dereferences the
 		// conditional ?/: operator tokens typia's programmers leave nil; the
-		// legacy text path filled them via normalizeNestiaSyntheticTokens before
-		// printing, so do the same here.
+		// so normalizeNestiaSyntheticTokens fills them before printing.
 		normalizeNestiaSyntheticTokens(result.AsNode())
 		return result
 	}
@@ -211,7 +209,7 @@ func nestiaCoreCollectMethodReplacements(
 		}
 		// @WebSocketRoute carries no injected validator (it is not a method kind),
 		// but its acceptor/driver parameter shapes are validated here, mirroring the
-		// legacy visitNestiaCoreNode path. Validate against the parse-tree method so
+		// collection pass. Validate against the parse-tree method so
 		// parameter type text resolves even when typia rebuilt this method.
 		if len(canonical) != 0 && canonical[len(canonical)-1] == "WebSocketRoute" {
 			for _, diag := range validateNestiaCoreWebSocketRoute(state.prog, context, nestiaCoreOriginalNode(state.ec, node), call, canonical) {

package/native/transform/printer.go

@@ -2,227 +2,10 @@ package transform
 
 import (
 	shimast "github.com/microsoft/typescript-go/shim/ast"
-	shimprinter "github.com/microsoft/typescript-go/shim/printer"
 )
 
 const nestiaKindColonToken = shimast.KindQuestionToken + 1
 
-func emitNestiaWithIdentifierSubstitutions(
-	node *shimast.Node,
-	sourceFile *shimast.SourceFile,
-	substitutions map[string]string,
-) string {
-	node = stripNestiaTypeSyntax(node)
-	node = rewriteNestiaIdentifiers(node, substitutions)
-	normalizeNestiaSyntheticTokens(node)
-	return emitNestiaNode(node, sourceFile)
-}
-
-func emitNestiaPreservingTypesWithIdentifierSubstitutions(
-	node *shimast.Node,
-	sourceFile *shimast.SourceFile,
-	substitutions map[string]string,
-) string {
-	node = rewriteNestiaIdentifiers(node, substitutions)
-	normalizeNestiaSyntheticTokens(node)
-	return emitNestiaNode(node, sourceFile)
-}
-
-func emitNestiaNode(node *shimast.Node, sourceFile *shimast.SourceFile) string {
-	return shimprinter.NewPrinter(shimprinter.PrinterOptions{
-		RemoveComments: true,
-		NewLine:        2,
-	}, shimprinter.PrintHandlers{}, nil).Emit(node, sourceFile)
-}
-
-func stripNestiaTypeSyntax(node *shimast.Node) *shimast.Node {
-	if node == nil {
-		return nil
-	}
-	factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
-	var visitor *shimast.NodeVisitor
-	visitor = shimast.NewNodeVisitor(func(current *shimast.Node) *shimast.Node {
-		if current == nil {
-			return nil
-		}
-		switch current.Kind {
-		case shimast.KindAsExpression, shimast.KindSatisfiesExpression, shimast.KindTypeAssertionExpression, shimast.KindNonNullExpression:
-			return visitor.VisitNode(current.Expression())
-		case shimast.KindVariableDeclaration:
-			decl := current.AsVariableDeclaration()
-			return factory.UpdateVariableDeclaration(
-				decl,
-				visitor.VisitNode(decl.Name()),
-				nil,
-				nil,
-				visitor.VisitNode(decl.Initializer),
-			)
-		case shimast.KindParameter:
-			parameter := current.AsParameterDeclaration()
-			return factory.UpdateParameterDeclaration(
-				parameter,
-				visitor.VisitModifiers(parameter.Modifiers()),
-				visitor.VisitNode(parameter.DotDotDotToken),
-				visitor.VisitNode(parameter.Name()),
-				nil,
-				nil,
-				visitor.VisitNode(parameter.Initializer),
-			)
-		case shimast.KindArrowFunction:
-			arrow := current.AsArrowFunction()
-			return factory.UpdateArrowFunction(
-				arrow,
-				visitor.VisitModifiers(arrow.Modifiers()),
-				nil,
-				visitor.VisitNodes(arrow.Parameters),
-				nil,
-				nil,
-				visitor.VisitNode(arrow.EqualsGreaterThanToken),
-				visitor.VisitNode(arrow.Body),
-			)
-		case shimast.KindCallExpression:
-			call := current.AsCallExpression()
-			return factory.UpdateCallExpression(
-				call,
-				visitor.VisitNode(call.Expression),
-				visitor.VisitNode(call.QuestionDotToken),
-				nil,
-				visitor.VisitNodes(call.Arguments),
-				call.Flags,
-			)
-		case shimast.KindNewExpression:
-			expr := current.AsNewExpression()
-			return factory.UpdateNewExpression(
-				expr,
-				visitor.VisitNode(expr.Expression),
-				nil,
-				visitor.VisitNodes(expr.Arguments),
-			)
-		default:
-			return visitor.VisitEachChild(current)
-		}
-	}, factory, shimast.NodeVisitorHooks{})
-	return visitor.VisitNode(node)
-}
-
-func rewriteNestiaIdentifiers(
-	node *shimast.Node,
-	substitutions map[string]string,
-) *shimast.Node {
-	if node == nil || len(substitutions) == 0 {
-		return node
-	}
-	factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
-	var visitor *shimast.NodeVisitor
-	visitor = shimast.NewNodeVisitor(func(current *shimast.Node) *shimast.Node {
-		if current == nil {
-			return nil
-		}
-		switch current.Kind {
-		case shimast.KindIdentifier:
-			if replacement, ok := substitutions[current.Text()]; ok {
-				return rewriteNestiaIdentifierExpression(factory, replacement)
-			}
-			return current
-		case shimast.KindVariableDeclaration:
-			decl := current.AsVariableDeclaration()
-			return factory.UpdateVariableDeclaration(
-				decl,
-				decl.Name(),
-				nil,
-				nil,
-				visitor.VisitNode(decl.Initializer),
-			)
-		case shimast.KindParameter:
-			parameter := current.AsParameterDeclaration()
-			return factory.UpdateParameterDeclaration(
-				parameter,
-				parameter.Modifiers(),
-				parameter.DotDotDotToken,
-				parameter.Name(),
-				nil,
-				nil,
-				visitor.VisitNode(parameter.Initializer),
-			)
-		case shimast.KindPropertyAssignment:
-			assignment := current.AsPropertyAssignment()
-			return factory.UpdatePropertyAssignment(
-				assignment,
-				assignment.Modifiers(),
-				assignment.Name(),
-				assignment.PostfixToken,
-				nil,
-				visitor.VisitNode(assignment.Initializer),
-			)
-		case shimast.KindShorthandPropertyAssignment:
-			assignment := current.AsShorthandPropertyAssignment()
-			name := assignment.Name()
-			if name != nil && name.Kind == shimast.KindIdentifier {
-				if replacement, ok := substitutions[name.Text()]; ok &&
-					assignment.ObjectAssignmentInitializer == nil {
-					return factory.NewPropertyAssignment(
-						assignment.Modifiers(),
-						name,
-						assignment.PostfixToken,
-						nil,
-						rewriteNestiaIdentifierExpression(factory, replacement),
-					)
-				}
-			}
-			return factory.UpdateShorthandPropertyAssignment(
-				assignment,
-				assignment.Modifiers(),
-				name,
-				assignment.PostfixToken,
-				nil,
-				nil,
-				visitor.VisitNode(assignment.ObjectAssignmentInitializer),
-			)
-		case shimast.KindPropertyAccessExpression:
-			access := current.AsPropertyAccessExpression()
-			return factory.UpdatePropertyAccessExpression(
-				access,
-				visitor.VisitNode(access.Expression),
-				access.QuestionDotToken,
-				access.Name(),
-				access.Flags,
-			)
-		default:
-			return visitor.VisitEachChild(current)
-		}
-	}, factory, shimast.NodeVisitorHooks{})
-	return visitor.VisitNode(node)
-}
-
-func rewriteNestiaIdentifierExpression(
-	factory *shimast.NodeFactory,
-	replacement string,
-) *shimast.Node {
-	parts := []string{}
-	start := 0
-	for i := 0; i <= len(replacement); i++ {
-		if i == len(replacement) || replacement[i] == '.' {
-			if start < i {
-				parts = append(parts, replacement[start:i])
-			}
-			start = i + 1
-		}
-	}
-	if len(parts) == 0 {
-		return factory.NewIdentifier(replacement)
-	}
-	output := factory.NewIdentifier(parts[0])
-	for _, part := range parts[1:] {
-		output = factory.NewPropertyAccessExpression(
-			output,
-			nil,
-			factory.NewIdentifier(part),
-			shimast.NodeFlagsNone,
-		)
-	}
-	return output
-}
-
 func normalizeNestiaSyntheticTokens(node *shimast.Node) {
 	if node == nil {
 		return

package/native/transform/run.go

@@ -42,6 +42,35 @@ func Run(args []string) (code int) {
 	return run(args)
 }
 
+// RunWithOutput is Run with the host's stdout and stderr writers redirected for
+// the duration of the call, then restored.
+//
+// The project-mode `transform` subcommand publishes its whole result — the
+// transformed sources, the diagnostics, and the reference graph — as one JSON
+// envelope on stdout, and unlike the single-file path it has no `--out` seam. An
+// exit code is therefore the only thing an external test module can observe
+// about it, which is not enough to pin what the envelope carries. This makes the
+// envelope itself observable without giving the CLI a flag ttsc never passes.
+//
+// Restoring inside the call keeps the redirect scoped: a nil writer is ignored,
+// so a caller can redirect one stream and leave the other on the process. The
+// writers are package state, so concurrent calls would interleave; the host runs
+// one command per process and Go tests in one package run sequentially unless
+// they opt into t.Parallel.
+func RunWithOutput(args []string, out io.Writer, errOut io.Writer) int {
+	previousOut, previousErr := stdout, stderr
+	defer func() {
+		stdout, stderr = previousOut, previousErr
+	}()
+	if out != nil {
+		stdout = out
+	}
+	if errOut != nil {
+		stderr = errOut
+	}
+	return Run(args)
+}
+
 func run(args []string) int {
 	if len(args) == 0 {
 		return runHelp(nil)

package/native/transform/transform.go

@@ -8,18 +8,40 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
-	"sort"
 	"strings"
 
 	shimast "github.com/microsoft/typescript-go/shim/ast"
 	shimprinter "github.com/microsoft/typescript-go/shim/printer"
 	"github.com/samchon/nestia/packages/core/native/plugin"
 	"github.com/samchon/ttsc/packages/ttsc/driver"
+	schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
 type transformProjectOutput struct {
 	Diagnostics []transformCompilerDiagnostic `json:"diagnostics,omitempty"`
 	TypeScript  map[string]string             `json:"typescript"`
+	// Graph is the host-owned reference graph of the loaded program produced by
+	// the ttsc driver SDK (driver.NewTransformGraph): direct resolved reference
+	// edges, ambient global-scope files, the tsconfig extends chain, and the
+	// module-resolution candidates that outrank a selected target. Keys and
+	// values share TypeScript's keying through driver.TransformOutputKey, so a
+	// consumer joins the sections by key.
+	//
+	// A bundler erases type-only imports from its own module graph, so without
+	// this section nothing tells a persistent filesystem cache that a generated
+	// validator depends on the DTO declaration it was generated from, and the
+	// cache replays the stale module after the DTO's type changes. Stamping it
+	// also moves `@ttsc/unplugin` off the whole-snapshot revalidation path onto
+	// its narrow per-file one. Omitted only for a nil or unloaded program, which
+	// cannot happen here: LoadProgram failures return before this point.
+	Graph *driver.TransformGraph `json:"graph,omitempty"`
+	// Dependencies maps each transformed file (same keys as TypeScript) to the
+	// source files owning the declarations typia's metadata analysis consulted
+	// while generating that file's validators and stringifiers. A consumer
+	// unions them with Graph rather than choosing between them, so the list is
+	// additive: an omission costs nothing, and narrowing would require the
+	// separate `dependenciesComplete` declaration this envelope does not make.
+	Dependencies map[string][]string `json:"dependencies,omitempty"`
 }
 
 type transformCompilerDiagnostic struct {
@@ -69,18 +91,19 @@ func runTransform(args []string) int {
 		return 2
 	}
 	defer prog.Close()
+	releaseTypiaRegistries := registerTypiaDefaultLibraryClassifier(prog)
+	defer releaseTypiaRegistries()
 
 	// AST-integration source-to-source: typia's, core's, and any linked
 	// contributor's per-file node transformers run inside one shared EmitContext
 	// and the result SourceFile is printed back as TypeScript (no JS script
 	// transformers), mirroring typia's `transform` subcommand. Injected namespace
-	// imports stay as ES imports the caller can type-strip per file, so there is
-	// no text-splice RewriteSet.
+	// imports stay as ES imports the caller can type-strip per file.
 	transformDiags := []Diagnostic{}
 	addDiagnostic := func(diag Diagnostic) {
 		transformDiags = append(transformDiags, diag)
 	}
-	typiaTransform := nestiaTypiaNodeTransform(prog, readTypiaPluginOptions(cwd, *tsconfigPath), addDiagnostic)
+	typiaTransform := nestiaTypiaNodeTransform(prog, readTypiaPluginOptions(plan), addDiagnostic)
 	coreTransform := nestiaCoreNodeTransform(prog, plan, addDiagnostic)
 	contributorTransforms, contributorDiags := collectContributorEmitTransforms(prog, plan)
 	if len(contributorDiags) > 0 {
@@ -125,16 +148,42 @@ func runTransformProject(
 		Diagnostics: []transformCompilerDiagnostic{},
 		TypeScript:  map[string]string{},
 	}
+	// Compute the reference graph from the loaded program before the transform
+	// loop runs: the graph must describe the original sources' resolved
+	// references, which are the transform's inputs, and the loop's printing pass
+	// sets parent pointers on the node tree it walks. ttsc's own `api-transform`
+	// host stamps it at the same point.
+	output.Graph = driver.NewTransformGraph(prog, cwd)
+	// `dependencies` is the second, narrower channel: the declaration files
+	// typia's analysis actually read for each file, reported alongside the graph
+	// rather than instead of it. The two are unioned by the consumer, so this
+	// list can only add inputs.
+	//
+	// The envelope deliberately declares no `dependenciesComplete`. That field
+	// transfers responsibility -- a listed file stops watching everything the
+	// reference closure carries -- and this host cannot honor it: whether a file
+	// is transformed at all depends on symbol resolutions that no listener
+	// reports, including the negative ones, and typia's own trigger set belongs
+	// to typia rather than to this host. See samchon/typia#2357.
+	collector := newTransformDependencyCollector(cwd, func(fileName string) bool {
+		sf := prog.SourceFile(fileName)
+		return sf != nil && prog.TSProgram.IsLibFile(sf)
+	})
+	schemametadata.MetadataDependency_listen(prog.Checker, collector.Touch)
+	defer schemametadata.MetadataDependency_release(prog.Checker)
 	for _, sf := range prog.SourceFiles() {
 		if sf.IsDeclarationFile {
 			continue
 		}
-		key := sourceFileKey(cwd, filepath.ToSlash(sf.FileName()))
+		key := driver.TransformOutputKey(cwd, sf.FileName())
 		if filepath.IsAbs(key) || key == ".." || strings.HasPrefix(key, "../") {
 			continue
 		}
+		collector.Begin(key)
 		output.TypeScript[key] = transformFileToTypeScript(prog, transforms, sf)
+		collector.End()
 	}
+	output.Dependencies = collector.ToJSON()
 	for _, diag := range *transformDiags {
 		output.Diagnostics = append(output.Diagnostics, transformDiagnosticToCompilerDiagnostic(diag))
 	}
@@ -196,32 +245,6 @@ func writeSingleOutput(text, outPath string) int {
 	return 0
 }
 
-type SourceRewrite struct {
-	start       int
-	end         int
-	replacement string
-}
-
-func ApplySourceRewrites(source string, rewrites []SourceRewrite) (string, error) {
-	sort.SliceStable(rewrites, func(i, j int) bool {
-		return rewrites[i].start > rewrites[j].start
-	})
-	for i := 0; i < len(rewrites)-1; i++ {
-		if rewrites[i+1].end > rewrites[i].start {
-			return "", fmt.Errorf("overlapping rewrites: [%d,%d) vs [%d,%d)",
-				rewrites[i+1].start, rewrites[i+1].end, rewrites[i].start, rewrites[i].end)
-		}
-	}
-	output := source
-	for _, rewrite := range rewrites {
-		if rewrite.start < 0 || rewrite.end < rewrite.start || rewrite.end > len(output) {
-			return "", fmt.Errorf("invalid rewrite range [%d,%d)", rewrite.start, rewrite.end)
-		}
-		output = output[:rewrite.start] + rewrite.replacement + output[rewrite.end:]
-	}
-	return output, nil
-}
-
 func SourceFileText(target any) (string, bool) {
 	type sourceText interface {
 		Text() string
@@ -244,79 +267,11 @@ var (
 	cleanupInputIsParenPattern      = regexp.MustCompile(`input is \(([A-Za-z_$][A-Za-z0-9_$.]*)\)`)
 	cleanupCollapseBlankCallPattern = regexp.MustCompile(`\n\n([A-Za-z_$][A-Za-z0-9_$]*\([^;\n]*\);?)`)
 )
-
-func cleanupTypeScriptTransformText(text string) string {
-	text = cleanupTransformedText(text)
-	text = normalizeParenthesizedTypeAnnotations(text)
-	text = cleanupImportTypeBlockPattern.ReplaceAllStringFunc(text, func(line string) string {
-		return cleanupImportTypeLinePattern.ReplaceAllString(line, "import type { $1 } from")
-	})
-	text = cleanupImportBlankLinePattern.ReplaceAllString(text, "$1$2")
-	text = strings.ReplaceAll(text, "=(() =>", "= (() =>")
-	text = strings.ReplaceAll(text, ": (any) =>", ": any =>")
-	text = strings.ReplaceAll(text, ": (boolean) =>", ": boolean =>")
-	text = cleanupInputIsParenPattern.ReplaceAllString(text, "input is $1")
-	text = strings.ReplaceAll(text, "return (success ? ", "return success ? ")
-	text = strings.ReplaceAll(text, "}) as any;", "} as any;")
-	text = strings.ReplaceAll(text, "(() => {\n    const ", "(() => { const ")
-	text = strings.ReplaceAll(text, "(() => {\n    let ", "(() => { let ")
-	text = strings.ReplaceAll(text, "(() => {\n    return ", "(() => { return ")
-	text = strings.ReplaceAll(text, ";\n    const ", "; const ")
-	text = strings.ReplaceAll(text, ";\n    let ", "; let ")
-	text = strings.ReplaceAll(text, ";\n    return ", "; return ")
-	text = strings.ReplaceAll(text, "\n    };\n})()", "\n}; })()")
-	text = strings.ReplaceAll(text, "\n    });\n})()", "\n}); })()")
-	text = strings.ReplaceAll(text, "\n    }); let ", "\n}); let ")
-	text = strings.ReplaceAll(text, ";\n})()", "; })()")
-	text = strings.ReplaceAll(text, "\n        ", "\n    ")
-	text = cleanupCollapseBlankCallPattern.ReplaceAllString(text, "\n$1")
-	trimmed := strings.TrimRight(text, " \t\r\n")
-	if strings.HasSuffix(trimmed, ")") && !strings.HasSuffix(trimmed, ";") {
-		return trimmed + ";\n"
-	}
-	if text != "" && !strings.HasSuffix(text, "\n") {
-		return text + "\n"
-	}
-	return text
-}
-
 var (
 	normalizeParenArrowTypePattern = regexp.MustCompile(`: \(([A-Za-z_$][A-Za-z0-9_$.]*(<[^()\n;{}]*>)?)\)(\s*=>)`)
 	normalizeParenNullishPattern   = regexp.MustCompile(`\| \((null|undefined)\)`)
 )
 
-func normalizeParenthesizedTypeAnnotations(text string) string {
-	text = normalizeParenArrowTypePattern.ReplaceAllString(text, ": $1$3")
-	text = normalizeParenNullishPattern.ReplaceAllString(text, "| $1")
-	return text
-}
-
-func sourceFileKey(cwd string, file string) string {
-	rel, err := filepath.Rel(cwd, filepath.FromSlash(file))
-	if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
-		return filepath.ToSlash(file)
-	}
-	return filepath.ToSlash(rel)
-}
-
-func newTransformCompilerDiagnostic(
-	file string,
-	code string,
-	message string,
-) transformCompilerDiagnostic {
-	var ptr *string
-	if file != "" {
-		normalized := filepath.ToSlash(file)
-		ptr = &normalized
-	}
-	return transformCompilerDiagnostic{
-		File:        ptr,
-		Category:    "error",
-		Code:        code,
-		MessageText: message,
-	}
-}
-
 func transformDiagnosticToCompilerDiagnostic(
 	diag Diagnostic,
 ) transformCompilerDiagnostic {

package/native/transform/typia_dependency.go

@@ -0,0 +1,117 @@
+package transform
+
+import (
+	"sort"
+	"strings"
+
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// transformDependencyCollector accumulates the declaration files typia's
+// metadata analysis reports while one project file is transformed, attributing
+// them to that file's envelope key.
+//
+// These are the envelope's `dependencies`: the source files owning the
+// declarations the analysis actually read to generate that file's validators and
+// stringifiers. A consumer unions them with the host-owned reference graph, so
+// the list is additive and an omission costs nothing; it never narrows anything
+// on its own. Narrowing is what `dependenciesComplete` would do, and this
+// envelope does not declare it -- see the note in runTransformProject.
+type transformDependencyCollector struct {
+	cwd     string
+	current string
+	files   map[string]map[string]bool
+	// isLibraryFile reports the compiler's own classification of a file as a
+	// default library. Classification must come from the program, never from a
+	// file-name pattern, for the reason registerTypiaDefaultLibraryClassifier
+	// records: a project's own ambient declaration file may legitimately be
+	// named `lib.custom.d.ts`, and dropping it by base name silently loses cache
+	// invalidation for the types it declares.
+	isLibraryFile func(fileName string) bool
+	// values memoizes fileName -> envelope value ("" for a dropped file). The
+	// listener reports the same declaration files repeatedly across call sites.
+	values map[string]string
+}
+
+func newTransformDependencyCollector(
+	cwd string,
+	isLibraryFile func(fileName string) bool,
+) *transformDependencyCollector {
+	return &transformDependencyCollector{
+		cwd:           cwd,
+		isLibraryFile: isLibraryFile,
+		files:         map[string]map[string]bool{},
+		values:        map[string]string{},
+	}
+}
+
+// Begin attributes subsequent touches to the given envelope key.
+func (collector *transformDependencyCollector) Begin(key string) {
+	collector.current = key
+}
+
+// End closes the window Begin opened, so a touch arriving between two files is
+// dropped rather than charged against whichever file happened to run last.
+func (collector *transformDependencyCollector) End() {
+	collector.current = ""
+}
+
+// Touch records one consulted declaration file for the current key. Default
+// library files, virtual URI sources (tsgo's `bundled:///` libraries), and the
+// transformed file itself are dropped: the first two are toolchain-versioned
+// rather than project inputs, and the third is already the cache key.
+func (collector *transformDependencyCollector) Touch(fileName string) {
+	if collector.current == "" {
+		return
+	}
+	value, memoized := collector.values[fileName]
+	if memoized == false {
+		value = collector.value(fileName)
+		collector.values[fileName] = value
+	}
+	if value == "" || value == collector.current {
+		return
+	}
+	set := collector.files[collector.current]
+	if set == nil {
+		set = map[string]bool{}
+		collector.files[collector.current] = set
+	}
+	set[value] = true
+}
+
+// value renders one reported file as its envelope key, or "" when it is dropped.
+// The key is driver.TransformOutputKey, the same one `typescript` and `graph`
+// use, so a consumer joins every section by key.
+func (collector *transformDependencyCollector) value(fileName string) string {
+	if strings.Contains(fileName, "://") || collector.isLibraryFile(fileName) {
+		return ""
+	}
+	return driver.TransformOutputKey(collector.cwd, fileName)
+}
+
+// ToJSON renders the collected sets as the envelope's `dependencies` map with
+// deterministically sorted values, or nil when nothing was collected. The nil
+// keeps the field off the wire entirely, which is what an envelope with nothing
+// to report must send.
+func (collector *transformDependencyCollector) ToJSON() map[string][]string {
+	if len(collector.files) == 0 {
+		return nil
+	}
+	output := map[string][]string{}
+	for key, set := range collector.files {
+		if len(set) == 0 {
+			continue
+		}
+		values := make([]string, 0, len(set))
+		for value := range set {
+			values = append(values, value)
+		}
+		sort.Strings(values)
+		output[key] = values
+	}
+	if len(output) == 0 {
+		return nil
+	}
+	return output
+}