ttsc 0.30.4 → 0.31.1

package/cmd/ttscserver/run_lsp_prefers_tsgo_flag_test.go

@@ -18,8 +18,16 @@ import (
 // 1. Substitute the runLSPServer seam and capture its options.
 // 2. Run runLSP with --stdio, --cwd, and --tsgo.
 // 3. Assert the captured TsgoBinary is the flag value.
+//
+// @evidence contracts/testing.md#behavioral-verification runLSP forwards an explicit --tsgo path into LSPServerOptions.TsgoBinary.
+// @evidence contracts/testing.md#independent-expectations The expected path is the literal constant the test passes.
+// @evidence contracts/testing.md#distinguishing-cases A distinct literal environment path competes with the explicit flag path, so ignoring the flag or preferring the environment is detected.
+// @evidence contracts/testing.md#execution-ownership This Go unit captures the owning runLSPServer seam and package-level writers. Plugin file/JSON environment transports are cleared with restoring controls before source construction, so no plugin query or host process starts. Flag and environment binary paths remain opaque option data.
 func TestRunLSPPrefersTsgoFlag(t *testing.T) {
   const expected = "/tmp/tsgo-test-binary"
+  t.Setenv("TTSC_TSGO_BINARY", "/tmp/tsgo-environment-binary")
+  t.Setenv("TTSC_LSP_PLUGINS_FILE", "")
+  t.Setenv("TTSC_LSP_PLUGINS_JSON", "")
   prev := runLSPServer
   var captured lspserver.LSPServerOptions
   runLSPServer = func(_ context.Context, opts lspserver.LSPServerOptions) error {
@@ -30,8 +38,9 @@ func TestRunLSPPrefersTsgoFlag(t *testing.T) {
 
   outBuf := &bytes.Buffer{}
   errBuf := &bytes.Buffer{}
+  expectedCwd := t.TempDir()
   withIO(t, outBuf, errBuf, nil, func() {
-    if code := runLSP([]string{"--stdio", "--cwd", t.TempDir(), "--tsgo", expected}); code != 0 {
+    if code := runLSP([]string{"--stdio", "--cwd", expectedCwd, "--tsgo", expected}); code != 0 {
       t.Fatalf("expected exit 0, got %d (stderr=%q)", code, errBuf.String())
     }
   })
@@ -39,4 +48,7 @@ func TestRunLSPPrefersTsgoFlag(t *testing.T) {
   if captured.TsgoBinary != expected {
     t.Fatalf("expected TsgoBinary %q, got %q", expected, captured.TsgoBinary)
   }
+  if captured.Cwd != expectedCwd {
+    t.Fatalf("expected explicit cwd %q, got %q", expectedCwd, captured.Cwd)
+  }
 }

package/cmd/ttscserver/run_lsp_reports_getwd_error_test.go

@@ -15,6 +15,11 @@ import (
 // 1. Substitute the getwd seam to return an error.
 // 2. Run runLSP with --stdio (no explicit --cwd).
 // 3. Assert exit 2 and a stderr message mentioning the working directory.
+//
+// @evidence contracts/testing.md#behavioral-verification runLSP without --cwd exits with status 2 and a 'could not resolve working directory' message when the working directory cannot be read.
+// @evidence contracts/testing.md#independent-expectations Status 2 and the message fragment are literals from the command contract; the failure is injected through the getwd seam.
+// @evidence contracts/testing.md#distinguishing-cases The explicit --cwd path avoids Getwd and is covered by sibling tests; this case is the implicit one.
+// @evidence contracts/testing.md#execution-ownership TestRunLSPReportsGetwdError is a Go unit test in the cmd/ttscserver package: it calls runLSP in-process with the runLSPServer or getwd seam replaced and captured streams, starting neither tsgo nor a product process.
 func TestRunLSPReportsGetwdError(t *testing.T) {
   prev := getwd
   getwd = func() (string, error) { return "", errors.New("synthetic getwd failure") }

package/cmd/ttscserver/run_lsp_reports_server_error_test.go

@@ -11,14 +11,21 @@ import (
 )
 
 // TestRunLSPReportsServerError pins the non-cancellation error path in
-// runLSP. When RunLSPServer reports a real failure (the upstream server
-// crashed, an unrecoverable IO error, etc.) the launcher must exit 1
-// and copy the error message to stderr.
+// runLSP. An authored sentinel from its owning host seam must produce exit 1
+// and the error text on stderr. Actual upstream crashes and native IO failures
+// are not exercised here.
 //
 // 1. Substitute the runLSPServer seam to return a sentinel error.
 // 2. Run runLSP with --stdio --cwd <tempdir>.
 // 3. Assert exit 1 and the sentinel text on stderr.
+//
+// @evidence contracts/testing.md#behavioral-verification runLSP exits with status 1 and prints the host's error text to stderr when the LSP host fails.
+// @evidence contracts/testing.md#independent-expectations Status 1 and the sentinel error text are literals returned by the substituted runLSPServer.
+// @evidence contracts/testing.md#distinguishing-cases The authored non-cancellation sentinel selects the failure branch; it does not simulate an actual upstream crash or IO fault.
+// @evidence contracts/testing.md#execution-ownership This Go unit replaces the owning runLSPServer seam and captures package-owned writers. Restoring empty file/JSON plugin-manifest environment controls isolate source construction before that seam, so no plugin query or host process starts; foreign process methods and streams are unchanged.
 func TestRunLSPReportsServerError(t *testing.T) {
+  t.Setenv("TTSC_LSP_PLUGINS_FILE", "")
+  t.Setenv("TTSC_LSP_PLUGINS_JSON", "")
   sentinel := errors.New("lsp host blew up")
   prev := runLSPServer
   runLSPServer = func(_ context.Context, _ lspserver.LSPServerOptions) error {

package/cmd/ttscserver/run_lsp_uses_native_plugin_manifest_source_test.go

@@ -12,27 +12,30 @@ import (
 )
 
 // TestRunLSPUsesNativePluginManifestSource verifies the command wires the
-// launcher-provided plugin manifest into the proxy source and then owns it.
+// authored empty manifest transports to native source construction and applies
+// their environment-clearing and file-consumption rules.
 //
-// A previous implementation always passed NullPluginSource, so editor sessions
-// could never receive ttsc plugin diagnostics or commands. The manifest also
-// names every resolved plugin and its launch context, so leaving it readable
-// for the process lifetime exposes it to any sidecar this host later spawns.
-// This test pins both halves of that seam without starting tsgo.
+// These fixtures contain no plugin entries. They observe the captured source
+// class, parent environment and file presence, not plugin entry transfer,
+// sidecar inheritance, maximum-byte limits, or a second editor launch.
 //
 //  1. Set the legacy TTSC_LSP_PLUGINS_JSON fallback to a valid manifest.
 //  2. Substitute runLSPServer and capture its LSPServerOptions.
 //  3. Run `ttscserver --stdio` and assert the native source is selected, and
-//     that the legacy payload no longer reaches a spawned sidecar.
+//     that the legacy payload is cleared from this process environment.
 //  4. Put a valid manifest in TTSC_LSP_PLUGINS_FILE while making the legacy
-//     environment payload invalid, and prove the bounded file transport wins,
-//     leaves neither variable behind, and survives the read because an editor
-//     that supplies it out of band must be able to launch twice.
+//     environment payload invalid, and prove file precedence, environment
+//     clearing, and continued file presence after this one invocation.
 //  5. Pass a manifest through --lsp-plugins-file while both environment forms
 //     are invalid, and prove the flag transport takes precedence and is
 //     consumed, because the launcher created that file for this process alone.
 //  6. Point the flag at a missing manifest and prove the command fails instead
 //     of silently serving a project without its declared plugins.
+//
+// @evidence contracts/testing.md#behavioral-verification The authored empty manifests yield a captured NativePluginSource and cleared parent manifest variables. The environment file wins over invalid JSON and remains present; the flag file wins over both invalid environment forms and is removed; a missing flag file gives a nonzero result naming the flag. Actual plugin entries, sidecars, size limits, file readability, and repeat launches are not asserted.
+// @evidence contracts/testing.md#independent-expectations The expected source selection, environment state and file transport are checked against literal manifests and variables the test sets.
+// @evidence contracts/testing.md#distinguishing-cases Legacy JSON, environment file and flag file use authored empty manifests; invalid competing transports distinguish precedence, and a missing flag target distinguishes admission failure. Environment-file retention contrasts with flag-file consumption.
+// @evidence contracts/testing.md#execution-ownership This Go unit replaces the owning runLSPServer seam and captures package-owned writers. It directly creates/inspects private manifest files and restores authored environment transports through t.Setenv. Empty plugin lists select no native query, and the host seam starts no process; foreign methods and process streams are unchanged.
 func TestRunLSPUsesNativePluginManifestSource(t *testing.T) {
   t.Setenv("TTSC_LSP_PLUGINS_JSON", `{"plugins":[],"lspPlugins":[]}`)
   t.Setenv("TTSC_LSP_PLUGINS_FILE", "")

package/cmd/ttscserver/run_lsp_uses_tsgo_environment_test.go

@@ -11,16 +11,23 @@ import (
 // TestRunLSPUsesTsgoEnvironment verifies TTSC_TSGO_BINARY feeds the native host
 // when no --tsgo flag is present.
 //
-// The JavaScript launcher resolves typescript and passes the
-// absolute path through this environment variable, keeping the Go binary thin
-// and independent of Node's module resolver.
+// The JavaScript launcher passes its selected upstream binary through this
+// environment variable. This unit treats the sentinel as opaque option data;
+// executable discovery, existence and child execution are not tested.
 //
 // 1. Set TTSC_TSGO_BINARY to a sentinel path.
 // 2. Substitute runLSPServer and capture its options.
 // 3. Assert TsgoBinary is populated from the environment.
+//
+// @evidence contracts/testing.md#behavioral-verification runLSP fills LSPServerOptions.TsgoBinary from TTSC_TSGO_BINARY when no --tsgo flag is given.
+// @evidence contracts/testing.md#independent-expectations The expected path is the literal sentinel set in the environment.
+// @evidence contracts/testing.md#distinguishing-cases The environment fallback contrasts with the explicit flag covered by its sibling test.
+// @evidence contracts/testing.md#execution-ownership This Go unit restores its authored environment sentinel, replaces the owning runLSPServer seam, and captures package-owned writers. Both plugin-manifest environment transports are cleared before source construction, so no plugin query or host process starts. It does not replace getwd or foreign process streams.
 func TestRunLSPUsesTsgoEnvironment(t *testing.T) {
   const expected = "/tmp/tsgo-env-binary"
   t.Setenv("TTSC_TSGO_BINARY", expected)
+  t.Setenv("TTSC_LSP_PLUGINS_FILE", "")
+  t.Setenv("TTSC_LSP_PLUGINS_JSON", "")
 
   prev := runLSPServer
   var captured lspserver.LSPServerOptions

package/driver/authored_region_maps_positions_around_the_preamble_test.go

@@ -0,0 +1,95 @@
+package driver
+
+import "testing"
+
+// TestAuthoredRegionMapsPositionsAroundThePreamble verifies the source-map
+// region adapter on sampled positions in four literal preamble-bearing texts.
+// It restores authored text, rejects the inside probe, maps the after probe,
+// and preserves the hashbang fixture's before probe.
+//
+// A preamble is parsed as part of the file, so a map printed from the Program
+// records positions in the preamble-bearing text. ApplySourcePreamble inserts
+// it after a BOM and after a hashbang line, and a preamble need not end a line,
+// so a fixed line shift would be wrong for all but the plainest case.
+//
+//  1. Insert a preamble into plain, CRLF hashbang, BOM, and open-line literal texts.
+//  2. Assert the authored text is the original, positions before the preamble
+//     stay, positions inside it drop, and positions after it land on the same
+//     authored character.
+//
+// @evidence contracts/testing.md#behavioral-verification Over four literal fixtures, authored text is restored, the sampled inside position is rejected, and the sampled after position maps to its literal authored coordinate; the hashbang fixture also checks one unchanged before position. Other coordinates, Unicode cases, and emitted source-map integration are not certified.
+// @evidence contracts/testing.md#independent-expectations The authored text and the expected line and column of each probe are literals written next to each input, not recomputed by the mapping.
+// @evidence contracts/testing.md#distinguishing-cases A plain file, a CRLF hashbang file, a BOM file and a preamble that does not end a line each place the preamble differently, so a fixed line shift fails all but the plainest case.
+// @evidence contracts/testing.md#execution-ownership This Go unit calls ApplySourcePreamble and the private region adapter in-process over literal text and an opaque filename. It creates no native file or compiler Program and starts no consumer or product process; emitted source-map rewriting is not exercised.
+func TestAuthoredRegionMapsPositionsAroundThePreamble(t *testing.T) {
+  type position struct{ line, column int }
+  cases := []struct {
+    name     string
+    authored string
+    preamble string
+    // before is a position ahead of the preamble, if the file has one.
+    before *position
+    // inside is a parsed position within the preamble.
+    inside position
+    // after maps a parsed position of `value` to its authored position.
+    after, authoredAfter position
+  }{
+    {
+      name:          "plain",
+      authored:      "export const value = 1;\n",
+      preamble:      "// one\n// two\n",
+      inside:        position{1, 3},
+      after:         position{2, 13},
+      authoredAfter: position{0, 13},
+    },
+    {
+      name:          "crlf hashbang",
+      authored:      "#!/usr/bin/env node\r\nexport const value = 1;\r\n",
+      preamble:      "// banner\n",
+      before:        &position{0, 5},
+      inside:        position{1, 0},
+      after:         position{2, 13},
+      authoredAfter: position{1, 13},
+    },
+    {
+      name:          "bom",
+      authored:      "\ufeffexport const value = 1;\n",
+      preamble:      "// banner\n",
+      inside:        position{0, 2},
+      after:         position{1, 13},
+      authoredAfter: position{0, 14},
+    },
+    {
+      name:          "open line",
+      authored:      "export const value = 1;\n",
+      preamble:      "/* banner */ ",
+      inside:        position{0, 4},
+      after:         position{0, 26},
+      authoredAfter: position{0, 13},
+    },
+  }
+  for _, c := range cases {
+    t.Run(c.name, func(t *testing.T) {
+      parsed := ApplySourcePreamble(c.authored, c.preamble)
+      region := newAuthoredRegion("/project/src/main.ts", parsed, c.preamble)
+      if region == nil {
+        t.Fatalf("no region for %q", parsed)
+      }
+      if region.text != c.authored {
+        t.Fatalf("authored text = %q, want %q", region.text, c.authored)
+      }
+      if c.before != nil {
+        if line, column, ok := region.authoredPosition(c.before.line, c.before.column); !ok || line != c.before.line || column != c.before.column {
+          t.Fatalf("before the preamble: got %d:%d ok=%v", line, column, ok)
+        }
+      }
+      if _, _, ok := region.authoredPosition(c.inside.line, c.inside.column); ok {
+        t.Fatalf("a position inside the preamble was kept")
+      }
+      line, column, ok := region.authoredPosition(c.after.line, c.after.column)
+      if !ok || line != c.authoredAfter.line || column != c.authoredAfter.column {
+        t.Fatalf("after the preamble: got %d:%d ok=%v, want %d:%d", line, column, ok, c.authoredAfter.line, c.authoredAfter.column)
+      }
+    })
+  }
+}

package/driver/build_information_uses_selected_output_identity_test.go

@@ -0,0 +1,148 @@
+package driver
+
+import (
+  "encoding/json"
+  "os"
+  "path/filepath"
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+  shimprinter "github.com/microsoft/typescript-go/shim/printer"
+)
+
+// TestBuildInformationUsesSelectedOutputIdentity Verifies incremental metadata
+// retains its compiler-selected identity across containment and map correction.
+//
+// File extensions do not define artifact kinds: selected state may end in .map
+// or .js, while an unrelated .tsbuildinfo outside the output boundary is not
+// metadata. All three emit lanes must retain the same compiler-selected state.
+//
+// 1. Load explicit, inferred, nonincremental, noEmit and semantic-error projects.
+// 2. Check selected state and unrelated suffix paths against containment and correction.
+// 3. Emit through raw, rewritten and plugin lanes and assert exact state/JS outputs.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual loaded Programs exercise outputEscapesOutDir, NewSourceMapCorrector and all three whole-program emit lanes; selected state is versioned JSON at its exact authored key and survives map correction without text changes, while unrelated outside suffix paths remain contained.
+// @evidence contracts/testing.md#independent-expectations Authored cache filenames and the pinned native inferred config-root state contract establish literal expected keys. Incremental/composite owns state eligibility independently of filename extension; noEmit forbids JavaScript, while disabled noEmitOnError permits partial output with an independently asserted TS2322.
+// @evidence contracts/testing.md#distinguishing-cases Contrasts .tsbuildinfo, .map, .js and extensionless selected state, default inference above outDir, a selected-looking nonincremental path, noEmit state-only output and semantic-error partial output. Adjacent unrelated .tsbuildinfo/.map names must not escape containment. All lanes share the same unchanged input generation and record their own writes.
+// @evidence contracts/testing.md#execution-ownership Go discovers this driver unit directly. Each case loads one owned temporary project and runs actual compiler/emitter operations in process; deferred Close releases its Program and no consumer, executable or native host is built.
+func TestBuildInformationUsesSelectedOutputIdentity(t *testing.T) {
+  for _, c := range []struct {
+    name        string
+    state       string
+    incremental bool
+    noEmit      bool
+    bad         bool
+  }{
+    {name: "standard", state: "cache/state.tsbuildinfo", incremental: true},
+    {name: "map", state: "cache/state.map", incremental: true},
+    {name: "javascript", state: "cache/state.js", incremental: true},
+    {name: "extensionless", state: "cache/state", incremental: true},
+    {name: "inferred", incremental: true},
+    {name: "nonincremental", state: "cache/state.tsbuildinfo"},
+    {name: "noEmit", state: "cache/state.map", incremental: true, noEmit: true},
+    {name: "partialError", state: "cache/state.map", incremental: true, bad: true},
+  } {
+    t.Run(c.name, func(t *testing.T) {
+      root := t.TempDir()
+      options := map[string]any{"target": "es2020", "module": "commonjs", "rootDir": "src", "outDir": "dist", "sourceMap": true, "incremental": c.incremental, "noEmit": c.noEmit, "noEmitOnError": false}
+      if c.state != "" {
+        options["tsBuildInfoFile"] = c.state
+      }
+      config, err := json.Marshal(map[string]any{"compilerOptions": options, "files": []string{"src/input.ts"}})
+      if err != nil {
+        t.Fatal(err)
+      }
+      if err = os.MkdirAll(filepath.Join(root, "src"), 0700); err != nil {
+        t.Fatal(err)
+      }
+      if err = os.WriteFile(filepath.Join(root, "tsconfig.json"), config, 0600); err != nil {
+        t.Fatal(err)
+      }
+      source := "export const value: number = 1;\n"
+      if c.bad {
+        source = "export const value: number = 'wrong';\n"
+      }
+      if err = os.WriteFile(filepath.Join(root, "src/input.ts"), []byte(source), 0600); err != nil {
+        t.Fatal(err)
+      }
+      p, diagnostics, err := LoadProgram(root, "tsconfig.json", LoadProgramOptions{SourcePreamble: "// source preamble\n"})
+      if err != nil || len(diagnostics) != 0 {
+        t.Fatalf("load: %v %v", err, diagnostics)
+      }
+      defer p.Close()
+      state := c.state
+      if state == "" {
+        state = "tsconfig.tsbuildinfo"
+      }
+      expected := filepath.ToSlash(filepath.Join(root, state))
+      if escaped := p.outputEscapesOutDir(expected); escaped == c.incremental {
+        t.Errorf("selected state containment: escaped=%v incremental=%v", escaped, c.incremental)
+      }
+      for _, decoy := range []string{"cache/unrelated.tsbuildinfo", "cache/unrelated.map"} {
+        if !p.outputEscapesOutDir(filepath.ToSlash(filepath.Join(root, decoy))) {
+          t.Errorf("unselected output escaped containment: %s", decoy)
+        }
+      }
+      if c.incremental {
+        original := `{"version":"unchanged-state","fileNames":["../src/input.ts"]}`
+        corrected, correctionErr := p.NewSourceMapCorrector()(expected, original)
+        if correctionErr != nil || corrected != original {
+          t.Errorf("selected state correction: %q %v", corrected, correctionErr)
+        }
+      }
+      if c.bad {
+        sawTypeError := false
+        for _, diagnostic := range p.Diagnostics() {
+          if diagnostic.Code == 2322 {
+            sawTypeError = true
+          }
+        }
+        if !sawTypeError {
+          t.Error("authored semantic error did not produce TS2322")
+        }
+      }
+      for _, lane := range []string{"raw", "rewrite", "plugin"} {
+        t.Run(lane, func(t *testing.T) {
+          writes := map[string]string{}
+          writer := func(file, text string, _ *shimcompiler.WriteFileData) error {
+            writes[filepath.ToSlash(file)] = text
+            return nil
+          }
+          var emitted []Diagnostic
+          var emitErr error
+          switch lane {
+          case "raw":
+            _, emitted, emitErr = p.EmitAllRaw(writer)
+          case "rewrite":
+            _, emitted, emitErr = p.EmitAll(NewRewriteSet(), writer)
+          case "plugin":
+            emitted, emitErr = p.EmitWithPluginTransformer(func(_ *shimprinter.EmitContext, source *shimast.SourceFile) *shimast.SourceFile { return source }, writer)
+          }
+          if emitErr != nil || len(emitted) != 0 {
+            t.Errorf("emit: %v %v", emitErr, emitted)
+          }
+          text, found := writes[expected]
+          if found != c.incremental {
+            t.Errorf("selected state presence=%v incremental=%v writes=%v", found, c.incremental, writes)
+          }
+          if found {
+            var document struct {
+              Version string `json:"version"`
+            }
+            if err := json.Unmarshal([]byte(text), &document); err != nil || document.Version == "" {
+              t.Errorf("state is not versioned JSON: %v %s", err, text)
+            }
+          }
+          javascript := filepath.ToSlash(filepath.Join(root, "dist/input.js"))
+          if (writes[javascript] != "") == c.noEmit {
+            t.Errorf("JavaScript presence contradicts noEmit=%v: %v", c.noEmit, writes)
+          }
+          if c.noEmit && len(writes) != 1 {
+            t.Errorf("noEmit must retain only state, got %v", writes)
+          }
+        })
+      }
+    })
+  }
+}

package/driver/check_observations.go

@@ -0,0 +1,67 @@
+package driver
+
+import (
+  "encoding/json"
+  "fmt"
+  "path/filepath"
+)
+
+// WriteCheckObservationsJSON publishes the linked-hook input observations of a
+// completed check invocation to its caller-owned absolute private path. The
+// caller must keep the Program open until this snapshot is written. Command
+// status and diagnostics remain independent of these observation facts.
+//
+// A nil Program publishes empty observation collections and an explicit incomplete
+// marker, because no generation supplied input authority. For a loaded Program,
+// only an explicit hook limitation adds that marker. Its absence does not prove
+// the population complete or repair missing or conflicting individual proofs.
+// The caller owns a fresh result path, its parent directory and eventual artifact
+// removal. Publication occurs only after a temporary write and close succeed.
+//
+// @evidence contracts/common.md#principled-implementation The same loaded Program supplies recorded input names and consistent supplied content and physical-path reports; missing generation authority is explicitly incomplete, while diagnostics and individual conflicts retain their independent meanings.
+// @evidence contracts/common.md#clear-and-simple-design One typed wire object keeps hook observations separate from human diagnostic streams and never reloads a second compiler generation to reconstruct them.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No later filesystem read or fabricated proof repairs a missing generation, unknown input or explicit observation limitation.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state absolute private-path ownership, Program lifetime, independent command status and the nil/absent-marker distinctions following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Native filepath admission and the shared same-directory publisher preserve host paths without shell parsing or separator substitution; observed physical names pass through unchanged.
+// @evidence contracts/performance.md#efficient-algorithms Each accessor snapshots and combines scope reports; input names and JSON map keys sort by text. Encoding and native publication include report population, path and value byte costs and temporary collection copies rather than only the final payload.
+// @evidence contracts/performance.md#reuse-equivalent-work The same check generation's recorded observations supply the result without reparsing sources or reexecuting configuration hooks.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Scope snapshots and encoding buffers are call-local without a payload cap. The shared publisher closes its temporary descriptor before rename and attempts removal on failure, returning cleanup errors; the caller owns the Program, fresh destination, parent directory and final artifact removal.
+func WriteCheckObservationsJSON(fileName string, program *Program) error {
+  if !filepath.IsAbs(fileName) {
+    return fmt.Errorf("driver: check observations path must be absolute: %q", fileName)
+  }
+  inputs := []string{}
+  hashes := map[string]*string{}
+  realpaths := map[string]*string{}
+  var complete *bool
+  var graph *TransformGraph
+  if program == nil || program.PluginObservationsIncomplete() {
+    unavailable := false
+    complete = &unavailable
+  }
+  if program != nil {
+    if program.TSProgram != nil {
+      graph = NewTransformGraph(program, program.TSProgram.GetCurrentDirectory())
+    }
+    if recorded := program.PluginHostInputs(); recorded != nil {
+      inputs = recorded
+    }
+    if recorded := program.PluginHostInputHashes(); recorded != nil {
+      hashes = recorded
+    }
+    if recorded := program.PluginHostInputRealpaths(); recorded != nil {
+      realpaths = recorded
+    }
+  }
+  data, err := json.Marshal(struct {
+    Graph                *TransformGraph    `json:"graph,omitempty"`
+    HostInputs           []string           `json:"hostInputs"`
+    HostInputHashes      map[string]*string `json:"hostInputHashes"`
+    HostInputRealpaths   map[string]*string `json:"hostInputRealpaths"`
+    ObservationsComplete *bool              `json:"observationsComplete,omitempty"`
+  }{graph, inputs, hashes, realpaths, complete})
+  if err != nil {
+    return err
+  }
+  return writePrivateResult(fileName, data)
+}