ttsc 0.26.2 → 0.27.0

package/README.md

@@ -30,6 +30,15 @@ npx ttsc --watch        # rebuild on save
 
 `ttsx` runs a file the way `tsx` or `ts-node` does, but it type-checks the whole project first, so a type error stops the run before anything executes.
 
+Preload the same checked runtime when Node or a test runner owns the process:
+
+```bash
+node --require ttsc/register src/index.ts
+mocha --require ttsc/register --extension ts,tsx "test/**/*.ts"
+```
+
+`ttsc/register` discovers the nearest `tsconfig.json` for each TypeScript root, applies its plugins, and refuses to execute when the project does not type-check.
+
 That covers the CLI. The integrations each have a short guide:
 
 - [`@ttsc/unplugin`](https://ttsc.dev/docs/setup/unplugin): Vite, Rollup, Rolldown, esbuild, webpack, Rspack, Next.js, Turbopack, Farm, and Bun.

package/cmd/ttsc/api_transform.go

@@ -26,6 +26,11 @@ type apiTransformResult struct {
   // content can influence a transformed module, so bundler caches invalidate
   // soundly without per-plugin reporting.
   Graph *driver.TransformGraph `json:"graph,omitempty"`
+  // HostInputs are absolute native plugin config files evaluated while this
+  // generation loaded. JavaScript hosts merge them with descriptor inputs.
+  HostInputs         []string           `json:"hostInputs,omitempty"`
+  HostInputHashes    map[string]*string `json:"hostInputHashes,omitempty"`
+  HostInputRealpaths map[string]*string `json:"hostInputRealpaths,omitempty"`
 }
 
 // runAPITransform implements the `api-transform` sub-command. It loads the
@@ -70,6 +75,9 @@ func runAPITransform(args []string) int {
   }
   typescript := map[string]string{}
   var graph *driver.TransformGraph
+  var hostInputs []string
+  var hostInputHashes map[string]*string
+  var hostInputRealpaths map[string]*string
   if prog != nil {
     defer prog.Close()
     // Compute the reference graph before SourceFiles() runs linked plugin
@@ -81,12 +89,18 @@ func runAPITransform(args []string) int {
       typescript[apiOutputKey(cwd, file.FileName())] = file.Text()
     }
     diags = append(diags, prog.Diagnostics()...)
+    hostInputs = prog.PluginHostInputs()
+    hostInputHashes = prog.PluginHostInputHashes()
+    hostInputRealpaths = prog.PluginHostInputRealpaths()
   }
 
   result := apiTransformResult{
-    Diagnostics: make([]apiCompileDiagnostic, 0, len(diags)),
-    TypeScript:  typescript,
-    Graph:       graph,
+    Diagnostics:        make([]apiCompileDiagnostic, 0, len(diags)),
+    Graph:              graph,
+    HostInputs:         hostInputs,
+    HostInputHashes:    hostInputHashes,
+    HostInputRealpaths: hostInputRealpaths,
+    TypeScript:         typescript,
   }
   for _, diag := range diags {
     result.Diagnostics = append(result.Diagnostics, toAPICompileDiagnostic(diag))

package/cmd/ttscgraph/auxiliary_identity_state_tracks_retargets_not_source_contents_test.go

@@ -0,0 +1,85 @@
+package main
+
+import (
+  "os"
+  "os/exec"
+  "path/filepath"
+  "runtime"
+  "testing"
+)
+
+// TestAuxiliaryIdentityStateTracksRetargetsNotSourceContents proves the two
+// owners of a selected lexical module path stay separate:
+//
+//  1. ordinary source bytes are owned by graphSession.sourceHashes, so an
+//     identity-only auxiliary state must not turn their edit into a reload;
+//  2. retargeting the same lexical symlink or junction must invalidate even
+//     when the old and new target bytes agree.
+func TestAuxiliaryIdentityStateTracksRetargetsNotSourceContents(t *testing.T) {
+  root := t.TempDir()
+  first := filepath.Join(root, "first")
+  second := filepath.Join(root, "second")
+  if err := os.MkdirAll(first, 0o755); err != nil {
+    t.Fatal(err)
+  }
+  if err := os.MkdirAll(second, 0o755); err != nil {
+    t.Fatal(err)
+  }
+  for _, directory := range []string{first, second} {
+    if err := os.WriteFile(filepath.Join(directory, "selection.ts"), []byte("export const value = 1;\n"), 0o644); err != nil {
+      t.Fatal(err)
+    }
+  }
+
+  link := filepath.Join(root, "linked")
+  createAuxiliaryDirectoryLink(t, first, link)
+  selected := filepath.Join(link, "selection.ts")
+  previous := captureDiskStates([]auxiliaryInput{{path: selected, identityOnly: true}})
+  initial := previous[selected]
+  if !initial.Exists || initial.Realpath == "" || !initial.IdentityOnly {
+    t.Fatalf("initial identity state = %+v", initial)
+  }
+
+  if err := os.WriteFile(filepath.Join(first, "selection.ts"), []byte("export const value = 2;\n"), 0o644); err != nil {
+    t.Fatal(err)
+  }
+  if diskStatesChanged(previous) {
+    t.Fatal("selected source contents leaked into identity-only auxiliary invalidation")
+  }
+
+  if err := os.Remove(link); err != nil {
+    t.Fatal(err)
+  }
+  createAuxiliaryDirectoryLink(t, second, link)
+  if !diskStatesChanged(previous) {
+    t.Fatal("same-byte lexical link retarget did not invalidate its physical identity")
+  }
+
+  merged := compactAuxiliaryInputs([]auxiliaryInput{
+    {path: selected, identityOnly: true},
+    {path: selected},
+  })
+  if len(merged) != 1 || merged[0].identityOnly {
+    t.Fatalf("content-sensitive duplicate did not win: %+v", merged)
+  }
+}
+
+func createAuxiliaryDirectoryLink(t *testing.T, target, link string) {
+  t.Helper()
+  if runtime.GOOS == "windows" {
+    command := exec.Command(
+      "node",
+      "-e",
+      `require("node:fs").symlinkSync(process.argv[1], process.argv[2], "junction")`,
+      target,
+      link,
+    )
+    if output, err := command.CombinedOutput(); err != nil {
+      t.Skipf("directory junction unavailable on this host: %v: %s", err, output)
+    }
+    return
+  }
+  if err := os.Symlink(target, link); err != nil {
+    t.Skipf("directory symlink unavailable on this host: %v", err)
+  }
+}

package/cmd/ttscgraph/disk_realpath_other.go

@@ -0,0 +1,16 @@
+//go:build !windows
+
+package main
+
+import "path/filepath"
+
+func diskRealpath(path string) string {
+  resolved, err := filepath.EvalSymlinks(path)
+  if err != nil {
+    return ""
+  }
+  if absolute, err := filepath.Abs(resolved); err == nil {
+    resolved = absolute
+  }
+  return filepath.Clean(resolved)
+}

package/cmd/ttscgraph/disk_realpath_windows.go

@@ -0,0 +1,56 @@
+//go:build windows
+
+package main
+
+import (
+  "path/filepath"
+  "strings"
+
+  "golang.org/x/sys/windows"
+)
+
+// diskRealpath asks the opened object for its final path. filepath.EvalSymlinks
+// can leave a readable file below a directory junction unresolved on Windows,
+// which would erase the physical identity this state exists to retain.
+func diskRealpath(path string) string {
+  pointer, err := windows.UTF16PtrFromString(path)
+  if err != nil {
+    return ""
+  }
+  handle, err := windows.CreateFile(
+    pointer,
+    windows.FILE_READ_ATTRIBUTES,
+    windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE,
+    nil,
+    windows.OPEN_EXISTING,
+    windows.FILE_FLAG_BACKUP_SEMANTICS,
+    0,
+  )
+  if err != nil {
+    return ""
+  }
+  defer windows.CloseHandle(handle)
+
+  buffer := make([]uint16, windows.MAX_PATH)
+  for {
+    length, err := windows.GetFinalPathNameByHandle(
+      handle,
+      &buffer[0],
+      uint32(len(buffer)),
+      0,
+    )
+    if err != nil {
+      return ""
+    }
+    if length < uint32(len(buffer)) {
+      resolved := windows.UTF16ToString(buffer[:length])
+      if strings.HasPrefix(resolved, `\\?\UNC\`) {
+        resolved = `\\` + strings.TrimPrefix(resolved, `\\?\UNC\`)
+      } else {
+        resolved = strings.TrimPrefix(resolved, `\\?\`)
+      }
+      return filepath.Clean(resolved)
+    }
+    buffer = make([]uint16, length+1)
+  }
+}

package/cmd/ttscgraph/serve.go

@@ -385,9 +385,11 @@ func (s *graphSession) captureState() error {
     return err
   }
   inputs := auxiliaryInputs(program, configs, s.cwd)
-  inputs = append(inputs, missingRootInputs(configs, sourceHashes)...)
+  for _, path := range missingRootInputs(configs, sourceHashes) {
+    inputs = append(inputs, auxiliaryInput{path: path})
+  }
   s.configHashes = configHashes
-  s.auxStates = captureDiskStates(compactSortedStrings(inputs))
+  s.auxStates = captureDiskStates(compactAuxiliaryInputs(inputs))
   s.sourceHashes = sourceHashes
   s.diskDigests = diskDigests
   s.rootFiles = projectRootFilesFromConfigs(configs, false)
@@ -661,8 +663,19 @@ func changedSources(previous map[string][sha256.Size]byte) (map[string]string, b
 }
 
 type diskState struct {
-  Hash   [sha256.Size]byte
-  Exists bool
+  Hash         [sha256.Size]byte
+  Exists       bool
+  Realpath     string
+  IdentityOnly bool
+}
+
+// auxiliaryInput distinguishes speculative inputs whose contents select the
+// build universe from the lexical spelling of the source the compiler already
+// selected. The resident source hash owns the latter's contents; this input
+// owns only whether the spelling still reaches the same physical file.
+type auxiliaryInput struct {
+  path         string
+  identityOnly bool
 }
 
 // captureDiskStates records the freshness state of speculative resolution
@@ -671,29 +684,35 @@ type diskState struct {
 // Windows), so any path that is neither a readable file nor a directory is
 // recorded as absent instead of failing the snapshot: the recorded state only
 // needs to flip when the candidate becomes resolvable.
-func captureDiskStates(paths []string) map[string]diskState {
-  states := make(map[string]diskState, len(paths))
-  for _, path := range paths {
-    content, err := os.ReadFile(path)
+func captureDiskStates(inputs []auxiliaryInput) map[string]diskState {
+  states := make(map[string]diskState, len(inputs))
+  for _, input := range inputs {
+    state := diskState{IdentityOnly: input.identityOnly}
+    content, err := os.ReadFile(input.path)
     if err != nil {
-      if info, statErr := os.Stat(path); statErr == nil && info.IsDir() {
-        states[path] = diskState{Exists: true}
-      } else {
-        states[path] = diskState{}
+      if info, statErr := os.Stat(input.path); statErr == nil && info.IsDir() {
+        state.Exists = true
+        state.Realpath = diskRealpath(input.path)
       }
+      states[input.path] = state
       continue
     }
-    states[path] = diskState{Hash: sha256.Sum256(content), Exists: true}
+    state.Exists = true
+    state.Realpath = diskRealpath(input.path)
+    if !input.identityOnly {
+      state.Hash = sha256.Sum256(content)
+    }
+    states[input.path] = state
   }
   return states
 }
 
 func diskStatesChanged(previous map[string]diskState) bool {
-  paths := make([]string, 0, len(previous))
-  for path := range previous {
-    paths = append(paths, path)
+  inputs := make([]auxiliaryInput, 0, len(previous))
+  for path, state := range previous {
+    inputs = append(inputs, auxiliaryInput{path: path, identityOnly: state.IdentityOnly})
   }
-  current := captureDiskStates(paths)
+  current := captureDiskStates(inputs)
   for path, state := range previous {
     if current[path] != state {
       return true
@@ -702,16 +721,16 @@ func diskStatesChanged(previous map[string]diskState) bool {
   return false
 }
 
-func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCommandLine, cwd string) []string {
-  inputs := []string{
-    filepath.Join(cwd, ".gitignore"),
-    filepath.Join(cwd, ".git", "info", "exclude"),
-    filepath.Join(cwd, "package.json"),
-    filepath.Join(cwd, "package-lock.json"),
-    filepath.Join(cwd, "pnpm-lock.yaml"),
-    filepath.Join(cwd, "yarn.lock"),
-    filepath.Join(cwd, "bun.lock"),
-    filepath.Join(cwd, "bun.lockb"),
+func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCommandLine, cwd string) []auxiliaryInput {
+  inputs := []auxiliaryInput{
+    {path: filepath.Join(cwd, ".gitignore")},
+    {path: filepath.Join(cwd, ".git", "info", "exclude")},
+    {path: filepath.Join(cwd, "package.json")},
+    {path: filepath.Join(cwd, "package-lock.json")},
+    {path: filepath.Join(cwd, "pnpm-lock.yaml")},
+    {path: filepath.Join(cwd, "yarn.lock")},
+    {path: filepath.Join(cwd, "bun.lock")},
+    {path: filepath.Join(cwd, "bun.lockb")},
   }
   for _, source := range program.TSProgram.SourceFiles() {
     file := source.FileName()
@@ -719,12 +738,18 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
       continue
     }
     directory := filepath.Dir(file)
-    inputs = appendAncestorInputs(inputs, directory, cwd)
+    for _, path := range appendAncestorInputs(nil, directory, cwd) {
+      inputs = append(inputs, auxiliaryInput{path: path})
+    }
     for _, reference := range source.ReferencedFiles {
-      inputs = append(inputs, driver.FileCandidates(filepath.Join(directory, filepath.FromSlash(reference.FileName)))...)
+      for _, path := range driver.FileCandidates(filepath.Join(directory, filepath.FromSlash(reference.FileName))) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
     for _, reference := range source.TypeReferenceDirectives {
-      inputs = append(inputs, driver.TypeReferenceCandidates(configs, directory, cwd, reference.FileName)...)
+      for _, path := range driver.TypeReferenceCandidates(configs, directory, cwd, reference.FileName) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
     for _, specifier := range driver.SourceModuleSpecifiers(source) {
       context := driver.ModuleResolutionContext{
@@ -738,7 +763,7 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
       }
       resolved := program.TSProgram.GetResolvedModuleFromModuleSpecifier(source, specifier)
       if resolved != nil && resolved.IsResolved() {
-        inputs = append(inputs, driver.ModuleResolutionPredecessors(
+        predecessors := driver.ModuleResolutionPredecessors(
           configs,
           directory,
           cwd,
@@ -746,10 +771,18 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
           resolved.ResolvedFileName,
           program.FS.UseCaseSensitiveFileNames(),
           context,
-        )...)
+        )
+        for _, path := range predecessors {
+          inputs = append(inputs, auxiliaryInput{
+            path:         path,
+            identityOnly: sameExistingAuxiliaryPath(path, resolved.ResolvedFileName),
+          })
+        }
         continue
       }
-      inputs = append(inputs, driver.ModuleResolutionCandidates(configs, directory, cwd, specifier.Text(), context)...)
+      for _, path := range driver.ModuleResolutionCandidates(configs, directory, cwd, specifier.Text(), context) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
   }
   // Config `types` entries request type packages without any source syntax, so
@@ -760,10 +793,46 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
       continue
     }
     for _, name := range parsed.ParsedConfig.CompilerOptions.Types {
-      inputs = append(inputs, driver.TypeReferenceCandidates(configs, parsed.GetCurrentDirectory(), cwd, name)...)
+      for _, path := range driver.TypeReferenceCandidates(configs, parsed.GetCurrentDirectory(), cwd, name) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
   }
-  return compactSortedStrings(inputs)
+  return compactAuxiliaryInputs(inputs)
+}
+
+func sameExistingAuxiliaryPath(left, right string) bool {
+  leftInfo, err := os.Stat(left)
+  if err != nil {
+    return false
+  }
+  rightInfo, err := os.Stat(right)
+  return err == nil && os.SameFile(leftInfo, rightInfo)
+}
+
+func compactAuxiliaryInputs(inputs []auxiliaryInput) []auxiliaryInput {
+  byPath := make(map[string]auxiliaryInput, len(inputs))
+  for _, input := range inputs {
+    if strings.TrimSpace(input.path) == "" {
+      continue
+    }
+    if previous, exists := byPath[input.path]; exists {
+      // A path that also participates as a manifest or other content-bearing
+      // input keeps the stronger content-sensitive contract.
+      input.identityOnly = previous.identityOnly && input.identityOnly
+    }
+    byPath[input.path] = input
+  }
+  paths := make([]string, 0, len(byPath))
+  for path := range byPath {
+    paths = append(paths, path)
+  }
+  sort.Strings(paths)
+  output := make([]auxiliaryInput, 0, len(paths))
+  for _, path := range paths {
+    output = append(output, byPath[path])
+  }
+  return output
 }
 
 func appendAncestorInputs(inputs []string, directory, stop string) []string {

package/driver/emit_plugin.go

@@ -1,7 +1,6 @@
 package driver
 
 import (
-  "context"
   "errors"
   "strings"
   "sync"
@@ -222,12 +221,30 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
       }
     }
   }
-  if !options.GetEmitDeclarations() {
+  // The declaration pass below doubles as this lane's build-information pass,
+  // so it also runs for a JavaScript-only `incremental` / `composite` project
+  // that has no declarations to write at all.
+  if !options.GetEmitDeclarations() && !p.emitsBuildInfo() {
     return nil, nil
   }
 
+  // What the build information this pass writes does and does not claim.
+  //
+  // The JavaScript above was hand-assembled and written outside tsgo's
+  // emitter, so tsgo's snapshot never saw it happen and records the JS emit of
+  // every file as still pending. That error is one-directional and safe: a
+  // consumer reading it can only decide to emit again, never to skip a file
+  // ttsc actually transformed. Making the record exact would mean running
+  // tsgo's own JavaScript emit a second time and discarding its output, paying
+  // a full emit to describe work already done. Everything else in the file —
+  // the compiler version, the resolved options, per-file versions and
+  // signatures, and the declaration state this pass does produce — is accurate.
+  //
+  // ttsc itself never reads build information back (see
+  // `shimcompiler.EmitFreshWithBuildInfo`), so this asymmetry costs a ttsc
+  // rebuild nothing.
   var wfMu sync.Mutex
-  result := p.TSProgram.Emit(context.Background(), shimcompiler.EmitOptions{
+  result := p.emitProgram(shimcompiler.EmitOptions{
     EmitOnly: shimcompiler.EmitOnlyDts,
     WriteFile: func(fileName string, text string, data *shimcompiler.WriteFileData) error {
       wfMu.Lock()

package/driver/graph.go

@@ -23,9 +23,10 @@ const bundledScheme = "bundled:///"
 //
 //   - Edges maps each file to its direct resolved references — imports,
 //     re-exports, `/// <reference>` targets, type reference directives, and
-//     ambient-module declaration files, type-only edges included. Direct
-//     edges are the minimal sufficient statistic; consumers that need a flat
-//     per-file list compute the reachability closure themselves.
+//     ambient-module declaration files, type-only edges included. A leaf file
+//     has an empty list so the node and its compiler-time input proof remain
+//     explicit. Direct edges are the minimal sufficient statistic; consumers
+//     that need a flat per-file list compute the reachability closure themselves.
 //   - Globals lists the files that contribute to the global scope (ambient
 //     declaration files, script files, global augmentations, `typeRoots`
 //     entries). A change to any of them can affect every file.
@@ -39,10 +40,12 @@ const bundledScheme = "bundled:///"
 // map: project-relative slash paths, falling back to slash-normalized
 // absolute paths outside the project root (see TransformOutputKey).
 type TransformGraph struct {
-  Edges      map[string][]string `json:"edges"`
-  Globals    []string            `json:"globals"`
-  Configs    []string            `json:"configs"`
-  Candidates map[string][]string `json:"candidates,omitempty"`
+  Edges          map[string][]string `json:"edges"`
+  Globals        []string            `json:"globals"`
+  Configs        []string            `json:"configs"`
+  Candidates     map[string][]string `json:"candidates,omitempty"`
+  InputHashes    map[string]*string  `json:"inputHashes,omitempty"`
+  InputRealpaths map[string]*string  `json:"inputRealpaths,omitempty"`
 }
 
 // NewTransformGraph computes the reference graph of a loaded program, keyed
@@ -69,16 +72,66 @@ func NewTransformGraph(prog *Program, cwd string) *TransformGraph {
     if shimcompiler.FileAffectsGlobalScope(file) {
       graph.Globals = append(graph.Globals, key)
     }
-    targets := referenceTargets(prog, cwd, file)
-    if len(targets) != 0 {
-      graph.Edges[key] = targets
-    }
+    // Keep leaf modules as empty adjacency-list entries. Besides making the
+    // graph's node universe explicit, this lets attachInputProof bind every
+    // source file to the bytes TypeScript-Go actually read. Omitting a leaf
+    // would let an A-B-A edit during compilation pair B's output with identical
+    // pre/post project snapshots for A.
+    graph.Edges[key] = referenceTargets(prog, cwd, file)
   }
   sort.Strings(graph.Globals)
   graph.Configs = configChain(prog, cwd)
+  graph.attachInputProof(prog, cwd)
   return graph
 }
 
+// attachInputProof pairs every graph path with the state the compiler
+// filesystem actually returned while constructing the resident Program. A
+// missing entry means proof was incomplete or contradictory; persistent hosts
+// then keep the fresh result but decline cross-build reuse.
+func (graph *TransformGraph) attachInputProof(prog *Program, cwd string) {
+  if prog == nil || prog.inputObserver == nil {
+    return
+  }
+  inputs := map[string]struct{}{}
+  for source, targets := range graph.Edges {
+    inputs[source] = struct{}{}
+    for _, target := range targets {
+      inputs[target] = struct{}{}
+    }
+  }
+  for _, input := range graph.Globals {
+    inputs[input] = struct{}{}
+  }
+  for _, input := range graph.Configs {
+    inputs[input] = struct{}{}
+  }
+  for source, candidates := range graph.Candidates {
+    inputs[source] = struct{}{}
+    for _, candidate := range candidates {
+      inputs[candidate] = struct{}{}
+    }
+  }
+  hashes := map[string]*string{}
+  realpaths := map[string]*string{}
+  for input := range inputs {
+    file := filepath.FromSlash(input)
+    if !filepath.IsAbs(file) {
+      file = filepath.Join(cwd, file)
+    }
+    hash, realpath, ok := prog.inputObserver.proof(file)
+    if !ok {
+      continue
+    }
+    hashes[input] = hash
+    realpaths[input] = realpath
+  }
+  if len(hashes) != 0 {
+    graph.InputHashes = hashes
+    graph.InputRealpaths = realpaths
+  }
+}
+
 // referenceTargets resolves one file's direct reference set to sorted envelope
 // keys, dropping bundled library files and the file itself.
 func referenceTargets(prog *Program, cwd string, file *ast.SourceFile) []string {