ttsc 0.30.3 → 0.31.0

package/driver/config_discovery.go

@@ -3,18 +3,31 @@ package driver
 import (
   "os"
   "path/filepath"
+
+  "github.com/microsoft/typescript-go/shim/vfs/osvfs"
 )
 
 // ConfigDiscovery is the result of one upward config-file search: what it
 // found, and what it looked at on the way.
+//
+// @evidence contracts/common.md#principled-implementation Matches and rejected probes are distinct; rejected path and directory classifications identify candidates to validate later without claiming their contents or independently verified absence.
+// @evidence contracts/common.md#clear-and-simple-design One search result carries stopping directory, ordered matches and rejected candidates; ambiguity policy stays with the plugin caller.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Candidate state is observed, not reconstructed from a plugin name or known project layout.
+// @evidence contracts/common.md#meaningful-documentation Native member paragraphs explain ordering, ambiguity and negative observations under documentation-skill guidance.
+// @evidence contracts/portability.md#os-neutral-implementation Paths retain native spellings; the result does not infer case policy or physical identity from the OS name.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
 type ConfigDiscovery struct {
   // Directory is the directory the search stopped in, empty when nothing
   // matched anywhere up to the filesystem root.
   Directory string
-  // Matches are the config files present in Directory, in the caller's name
+
+  // Matches are the non-directory candidates statted successfully in Directory, in the caller's name
   // order. More than one is the ambiguity each plugin reports in its own
   // words; none means the search reached the root.
   Matches []string
+
   // Probed are the candidates the search examined and rejected, in every
   // directory it visited up to and including Directory.
   //
@@ -25,31 +38,53 @@ type ConfigDiscovery struct {
   // config a cold run would no longer choose, which is why a plugin reports
   // them as host inputs rather than dropping them.
   //
-  // A rejected candidate is usually absent, but a directory carrying a config
-  // file's name is rejected too, and the two are not the same observation: the
-  // host-input contract records an existing directory by its directory-kind
-  // digest and its physical path, so that replacing it with a file invalidates
-  // the generation. Reporting one as absent instead makes every consumer's
-  // check disagree with its own filesystem forever.
+  // Rejected candidates include successfully observed directories and all stat
+  // failures, whose individual reasons are not retained here. Reporting uses a
+  // directory-kind digest for the former and a physical path only when later
+  // resolution succeeds; the latter use the protocol's observed-missing class.
+  // A consumer owns later validation and can reject reuse when these reported
+  // states conflict with what its own filesystem observes.
   Probed []ConfigCandidate
 }
 
-// ConfigCandidate is one path a config search rejected, and what it found
-// there.
+// ConfigCandidate is one path a config search rejected and its directory
+// classification. Stat failures and other non-matches share the false class;
+// the value carries no error reason or independently verified absence receipt.
+//
+// @evidence contracts/common.md#principled-implementation A path and directory discriminator distinguish a successfully observed directory from the search's other rejected candidates; false does not certify physical absence.
+// @evidence contracts/common.md#clear-and-simple-design The value records only the discovery facts consumed by rejected-input reporting.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Directory state is supplied by a filesystem observation, not a filename heuristic.
+// @evidence contracts/common.md#meaningful-documentation Native member comments describe the directory flag and absolute path following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Native paths and directory status remain separate; no separator or case capability is encoded as an OS guess.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
 type ConfigCandidate struct {
   // Directory reports that the path exists and is a directory.
   Directory bool
-  // Path is the candidate's absolute location.
+
+  // Path is the candidate spelling, absolute when discovery's caller supplies
+  // the documented absolute base and config filename inputs.
   Path string
 }
 
 // DiscoverConfigFile walks upward from base looking for any of names in each
 // directory, stopping at the first directory that contains at least one.
 //
-// The walk is the one every first-party utility plugin runs for its
+// Banner and strip use this shared walk for their
 // `<plugin>.config.*` file. It is shared here so the set of superseding
 // candidates is derived by the same rule everywhere, since that set is the part
 // a consumer needs and the part each plugin was most likely to leave out.
+// Pass an absolute base so returned candidates have the host's absolute form.
+//
+// @evidence contracts/common.md#principled-implementation Every supplied name is statted before stopping at the nearest matching ancestor, preserving ambiguity and superseding negative candidates.
+// @evidence contracts/common.md#clear-and-simple-design One upward walk owns discovery while callers decide how multiple matches become plugin diagnostics.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Names are caller policy; the search has no repository-specific branch or fabricated missing-file result.
+// @evidence contracts/common.md#meaningful-documentation Native prose states search stopping, shared observation ownership and the absolute-base precondition under documentation-skill guidance.
+// @evidence contracts/portability.md#os-neutral-implementation filepath.Join and Dir handle native ancestry and root termination; os.Stat obtains actual directory state without an OS case guess.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Native stat owns its temporary resources; the function keeps no handles or historical search state. Candidate slices and path strings are transferred to the caller, whose lifetime is not controlled here.
+// @evidence contracts/performance.md#efficient-algorithms Each visited directory probes every supplied name before deciding whether to stop: O(depth x names) native stat calls plus candidate-path construction and retained rejected-path bytes. This preserves same-directory ambiguity and nearer rejected candidates without enumerating directory contents.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation owns no cross-search cache or coordinator; it returns observed candidate states, while callers own later validation and any repeated native observations.
 func DiscoverConfigFile(base string, names []string) ConfigDiscovery {
   out := ConfigDiscovery{}
   directory := base
@@ -65,6 +100,10 @@ func DiscoverConfigFile(base string, names []string) ConfigDiscovery {
       case err == nil:
         probed = append(probed, ConfigCandidate{Directory: true, Path: candidate})
       default:
+        // Any stat failure (absent, permission-denied, not-a-directory
+        // ancestor) is reported as absent: the compiler's own filesystem
+        // exposes existence as a boolean, so its observer records the same
+        // state for the same path and the two proofs agree.
         probed = append(probed, ConfigCandidate{Path: candidate})
       }
     }
@@ -85,20 +124,27 @@ func DiscoverConfigFile(base string, names []string) ConfigDiscovery {
 // ReportRejectedConfigCandidates declares every candidate a config search
 // rejected, so a consumer invalidates when one of them becomes the answer.
 //
-// Each candidate is reported in the state it was found in, because the
-// host-input contract distinguishes them. An absent path takes the paired nil
-// hash and nil realpath, which records the absence as observed state rather
-// than as an unknown and is what lets a persistent adapter keep its narrow
-// reuse instead of declining it. A directory takes the directory-kind digest
-// and its own physical path, the same shape the compiler's own resolution
-// probes record, so that replacing it with a real config file invalidates the
-// generation. Reporting a directory as absent instead leaves every consumer
-// comparing nil against a digest its filesystem keeps producing, and the
-// generation is refused on every delivery for the rest of its life.
+// A candidate not classified as a directory reports nil hash and nil realpath
+// as the protocol's observed-missing state. Discovery also uses this class for
+// stat failures; reporting does not independently verify physical absence.
+// A directory reports the directory-kind digest and a physical path only when
+// Abs and EvalSymlinks succeed. Failure to resolve that path leaves its realpath
+// report unavailable. Later consumers own validation against their filesystem;
+// a conflicting directory-versus-missing observation prevents that reuse while
+// the mismatch remains, rather than being treated as an unknown observation.
 //
 // Takes the two reporters rather than a PluginContext so a plugin that already
 // threads them through its config loader can call it there, which is where the
 // discovery result lives.
+//
+// @evidence contracts/common.md#principled-implementation Missing candidates report nil observations; directories report the kind digest and a resolved physical target only when available.
+// @evidence contracts/common.md#clear-and-simple-design Two callbacks receive the search's already observed states without requiring a whole plugin context.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts An unresolved directory target is omitted rather than falsely reported as observed missing.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain nil-versus-unknown state, invalidation and callback ownership under documentation-skill guidance.
+// @evidence contracts/portability.md#os-neutral-implementation The compiler's OS filesystem resolves native physical names, including Windows junctions and short names. Directory Stat identities bracket that resolution; missing, replaced or non-directory targets leave the realpath observation unavailable.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Digest and resolved-path pointers are passed to caller-owned reporters, which may copy or retain them. This function retains no historical state or native handle; native resolution owns its temporary resources and reporter-owned retained bytes have no bound enforced here.
+// @evidence contracts/performance.md#efficient-algorithms One pass processes all candidates; directory candidates add native absolute-path and symlink-resolution work driven by path length and link components. Each supplied reporter is called at most once per applicable candidate, with its own processing and retention costs.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This function coordinates no repeated requests or cache; it transfers each applicable observation to the supplied reporters, whose validation and sharing policies remain separate.
 func ReportRejectedConfigCandidates(candidates []ConfigCandidate, hashReporter, realpathReporter func(string, *string)) {
   for _, candidate := range candidates {
     var hash *string
@@ -111,9 +157,32 @@ func ReportRejectedConfigCandidates(candidates []ConfigCandidate, hashReporter,
         // junctions). The descriptor-side observer reports a physical path, so
         // publishing the lexical spelling here would make the two proofs
         // conflict and leave every persistent consumer unable to reuse.
-        if physical, err := filepath.EvalSymlinks(resolved); err == nil {
-          cleaned := filepath.Clean(physical)
-          realpath = &cleaned
+        before, beforeErr := os.Stat(resolved)
+        if beforeErr == nil && before.IsDir() {
+          physical := osvfs.FS().Realpath(resolved)
+          // Realpath returns its argument if the native resolver fails. An
+          // unchanged spelling is proof only when no component is an alias or
+          // unknown reparse entry; SameFile alone cannot prove its spelling.
+          spellingKnown := true
+          if physical == resolved {
+            for component := resolved; ; component = filepath.Dir(component) {
+              entry, err := os.Lstat(component)
+              if err != nil || !entry.IsDir() || entry.Mode()&(os.ModeSymlink|os.ModeIrregular) != 0 {
+                spellingKnown = false
+                break
+              }
+              if filepath.Dir(component) == component {
+                break
+              }
+            }
+          }
+          target, targetErr := os.Stat(physical)
+          after, afterErr := os.Stat(resolved)
+          if spellingKnown && filepath.IsAbs(physical) && targetErr == nil && afterErr == nil &&
+            target.IsDir() && after.IsDir() && os.SameFile(before, target) && os.SameFile(before, after) {
+            cleaned := filepath.Clean(physical)
+            realpath = &cleaned
+          }
         }
       }
     }

package/driver/declaration_shape.go

@@ -16,6 +16,15 @@ import (
 // derives for one source file. Resident consumers compare the old and new
 // values to distinguish a private body edit from a public semantic movement
 // before expanding invalidation through reverse dependencies.
+//
+// @evidence contracts/common.md#principled-implementation TypeScript's own declaration emitter defines public shape; a no-output fallback conservatively hashes source rather than pretending the shape is unchanged.
+// @evidence contracts/common.md#clear-and-simple-design One forced declaration emit feeds a signature builder and SHA-256 digest; diagnostic structure contributes through one helper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Public shape is not guessed from syntax or patched to match expected invalidation examples.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains public versus private movement and resident invalidation purpose following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Diagnostic filenames use compiler path-relative operations; the digest has no guessed OS case policy or native separator serialization.
+// @evidence contracts/performance.md#efficient-algorithms Generation-latched linked hooks precede selected-source forced declaration emit, whose compiler/checker/transform work is delegated. Output and recursive diagnostic text accumulate in a builder before a byte conversion and SHA256 scan; native diagnostic path/text work and output size/depth have no wrapper cap or deadline.
+// @evidence contracts/performance.md#reuse-equivalent-work The method reuses the loaded program and latched linked-hook outcome; declaration-shape reuse across generations is owned by the resident consumer.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The builder, emitted text and digest conversion are call-local without a payload cap; the digest transfers to its consumer. Borrowed Program/checker/latched-hook state remains with its generation owner; this method acquires no file descriptor or lease, and context.Background supplies no caller cancellation.
 func (p *Program) DeclarationShapeDigest(file *ast.SourceFile) (string, error) {
   if p == nil || p.TSProgram == nil || file == nil {
     return "", fmt.Errorf("driver: declaration shape requires a loaded source file")

package/driver/diagnostics_preamble.go

@@ -14,9 +14,9 @@ import (
 // at the SOURCE level: sourcePreambleFS prepends it before TypeScript-Go parses,
 // so the preamble participates in comment emission, removeComments, JSDoc
 // association, and `.d.ts` emit naturally. The side effect is that every
-// position tsgo records — including every diagnostic's — is shifted down by the
-// preamble's line count, while the file the user reads has no preamble. The
-// emitted source map already undoes that shift (AdjustEmittedSourceMap); this is
+// position tsgo records — including every diagnostic's — describes the injected
+// buffer, while the file the user reads has no preamble. Native source maps use
+// Program.NewSourceMapCorrector to remove the exact injected region; this is
 // the same invariant applied to the other coordinate the user is shown.
 //
 // The correction lives here, at the Program boundary where the preamble is
@@ -38,10 +38,12 @@ import (
 // diagnostic.
 type preambleView struct {
   file *ast.SourceFile
+
   // start is the byte offset where the preamble was inserted, and length its
   // byte length. ApplySourcePreamble inserts after a BOM and after a hashbang
   // line, so start is not always zero.
-  start  int
+  start int
+
   length int
 }
 
@@ -86,9 +88,8 @@ const sourcePreambleBOM = "\ufeff"
 // file, a `.json` input, a library file) simply does not match and is reported
 // as having no region.
 //
-// One degenerate shape is nominally off by one, matching the same allowance
-// AdjustSourceMapForPreamble states: a file whose entire content is a hashbang
-// with no trailing newline gets the preamble appended after an inserted newline,
+// One degenerate shape is nominally off by one: a file whose entire content is
+// a hashbang with no trailing newline gets the preamble appended after an inserted newline,
 // which is indistinguishable from an authored trailing newline. Only a position
 // at that file's very end could differ, and such a file has no code to diagnose.
 func sourcePreambleRegion(filePath, text, preamble string) (start int, length int, ok bool) {

package/driver/emit_containment.go

@@ -5,7 +5,7 @@
 // (`--emit`, a plugin host's runBuild) intentionally proceed past that guard,
 // and tsgo then computes the output path of an out-of-rootDir source relative
 // to the common source directory — which resolves to a `.js` right next to the
-// dependency's own source (issue #293). The classic trigger is package
+// dependency's own source. The classic trigger is package
 // self-reference: a project nested inside a dependency's directory resolves
 // the dependency's name without a node_modules hop, so its sources are not
 // classified as external-library files and stay in the emit set.
@@ -15,18 +15,39 @@
 // same way tsc treats node_modules externals (no emit, no error).
 package driver
 
-import (
-  "strings"
+import "github.com/microsoft/typescript-go/shim/tspath"
 
-  "github.com/microsoft/typescript-go/shim/tspath"
-)
+// isBuildInfoOutput identifies the metadata artifact selected by this compiler
+// generation. Its configured extension does not determine its kind, and an
+// unrelated .tsbuildinfo path must not acquire metadata privileges.
+//
+// Private Go helpers are reviewed through their emit owners rather than selected
+// as exported Evidence hosts.
+// Common: Principled implementation: The loaded command line computes the same explicit or inferred build-information destination as native emission, including incremental eligibility; compiler path comparison establishes exact lexical identity under the Program's case policy.
+// Common: Clear and simple design: One artifact predicate serves containment and source-map correction rather than independent suffix rules.
+// Common: Prohibited implementation shortcuts: The real compiler-selected path replaces the suffix exception; no API-specific filename or consumer exemption compensates for output loss.
+// Common: Meaningful documentation: Native prose distinguishes selected artifact identity from filename extension and explains why unrelated metadata-looking paths remain ordinary outputs.
+// Portability: OS-neutral implementation: Native compiler path comparison uses the loaded Program's current directory and actual case policy, without assuming case behavior from the operating system.
+// Performance: Efficient algorithms: Upstream destination inference and lexical comparison process a bounded number of path strings with costs proportional to their text; no directory traversal or file read is added.
+// Performance: Reuse equivalent work: The current compiler generation owns destination selection; this predicate introduces no result cache or independent producer.
+// Performance: Bound retention and release resources: The predicate returns a boolean and retains no compiler generation, path history or external resource.
+func (p *Program) isBuildInfoOutput(fileName string) bool {
+  if p == nil || p.TSProgram == nil {
+    return false
+  }
+  buildInfo := p.TSProgram.CommandLine().GetBuildInfoFileName()
+  return buildInfo != "" && tspath.ComparePaths(buildInfo, fileName, tspath.ComparePathsOptions{
+    UseCaseSensitiveFileNames: p.TSProgram.UseCaseSensitiveFileNames(),
+    CurrentDirectory:          p.TSProgram.GetCurrentDirectory(),
+  }) == 0
+}
 
 // outputEscapesOutDir reports whether fileName — an emit output path tsgo
 // computed for this program — would land outside the project's configured
 // `outDir` (and `declarationDir`, when set). Projects without `outDir` emit
 // next to their sources by design, so the guard only applies when `outDir`
-// gives the project an output boundary. `.tsbuildinfo` is exempt because its
-// default location is next to the tsconfig, legitimately outside `outDir`.
+// gives the project an output boundary. The compiler-selected build-information
+// artifact is exempt because its location can legitimately be outside outDir.
 func (p *Program) outputEscapesOutDir(fileName string) bool {
   if p == nil || p.TSProgram == nil {
     return false
@@ -35,7 +56,7 @@ func (p *Program) outputEscapesOutDir(fileName string) bool {
   if options.OutDir == "" {
     return false
   }
-  if strings.HasSuffix(fileName, ".tsbuildinfo") {
+  if p.isBuildInfoOutput(fileName) {
     return false
   }
   cmp := tspath.ComparePathsOptions{

package/driver/emit_plugin.go

@@ -4,7 +4,6 @@ import (
   "context"
   "errors"
   "fmt"
-  "strings"
   "sync"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
@@ -76,16 +75,37 @@ func (h *pluginEmitHost) IsSourceFileFromExternalLibrary(file *shimast.SourceFil
 }
 
 // PluginTransform transforms one source file in the emit phase, bound to the
-// emit EmitContext: nodes it builds with ec.Factory (and links with
-// ec.SetOriginal) are recognized and aliased by tsgo's builtin module-transform.
+// emit EmitContext. ec.Factory and ec.SetOriginal supply the identity channels
+// used by builtin transforms; they do not make every arbitrary constructed tree
+// valid. Injected bindings must use the supported generated-name policy and
+// preserve the original links needed by the particular transformation.
 // Returning nil leaves the file unchanged. This is the AST-integration contract
 // that replaces text-splice: a plugin returns AST, not text. The shape mirrors a
-// classic ts.TransformerFactory (SourceFile -> SourceFile) so an existing
-// node-based transformer plugs in by just accepting the EmitContext.
+// classic source-file transformer, with EmitContext supplied on each call;
+// adapting an existing transformer still requires the native AST and context
+// APIs rather than only changing its function signature.
+//
+// @evidence contracts/common.md#principled-implementation Generated AST identity belongs to the shared emit context, allowing builtin import and module transforms to interpret plugin nodes.
+// @evidence contracts/common.md#clear-and-simple-design A per-source callback returns an optional replacement; the host owns ordering and printing.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The supported AST factory and original links replace textual alias guesses or patched compiler methods.
+// @evidence contracts/common.md#meaningful-documentation Native prose specifies context identity, nil behavior, and source transformation following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The callback signature defines AST work rather than native path or process operations.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Concrete callbacks select their algorithms; the signature performs no traversal.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The signature owns no shared-work coordinator.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Resource lifetime belongs to the concrete callback and emit owner, not this function type.
 type PluginTransform func(ec *shimprinter.EmitContext, sourceFile *shimast.SourceFile) *shimast.SourceFile
 
 // EmitWithPluginTransformer emits with a single plugin transformer. It is a thin
 // wrapper over EmitWithPluginTransformers.
+//
+// @evidence contracts/common.md#principled-implementation The single-transform entry uses the same linked-plugin and builtin emit pipeline as the multi-transform entry.
+// @evidence contracts/common.md#clear-and-simple-design One slice construction delegates all emit policy to EmitWithPluginTransformers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No alternate single-transform path bypasses linked hooks or error handling.
+// @evidence contracts/common.md#meaningful-documentation The native comment identifies the single-transform convenience role following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The delegated emitter owns native output paths and filesystem behavior.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The delegated emitter owns traversal and printing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The delegated emitter owns generation hook reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The wrapper acquires no separate resource or retained buffer.
 func (p *Program) EmitWithPluginTransformer(transform PluginTransform, writeFile shimcompiler.WriteFile) ([]Diagnostic, error) {
   return p.EmitWithPluginTransformers([]PluginTransform{transform}, writeFile)
 }
@@ -94,6 +114,15 @@ func (p *Program) EmitWithPluginTransformer(transform PluginTransform, writeFile
 // host-owned transformer. It is the no-transform convenience form of
 // EmitWithPluginTransformers, which honors linked plugins on every emit it
 // runs.
+//
+// @evidence contracts/common.md#principled-implementation Omitting host transforms still honors the project's linked transform hooks through the shared pipeline.
+// @evidence contracts/common.md#clear-and-simple-design A nil host-transform list delegates all scheduling and output policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Linked-only emit does not silently skip registrations because the caller supplied no transform.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes linked-only and host-owned transforms following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The delegated emitter owns native output operations.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The shared emitter owns traversal and printing.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The shared emitter owns hook latching.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This wrapper acquires no independent retained resource.
 func (p *Program) EmitLinkedTransforms(writeFile shimcompiler.WriteFile) ([]Diagnostic, error) {
   return p.EmitWithPluginTransformers(nil, writeFile)
 }
@@ -107,14 +136,11 @@ func (p *Program) EmitLinkedTransforms(writeFile shimcompiler.WriteFile) ([]Diag
 // because the emit context's update hook only records the original, it does not
 // copy `DeclarationBase.Symbol`.
 //
-// #201 added this against a real panic in the walk that
-// MarkLinkedReferencesRecursively used to run over the transformed tree. That
-// walk no longer happens here — the builtin chain is built from the parse tree
-// below — so the original trigger is gone, and no probe reproduces a panic with
-// this call stubbed out.
-//
-// Keep it anyway, because the remaining exposure is unproven rather than
-// absent. tsgo's own defense against a plugin-built node is ast.IsParseTreeNode,
+// It guards the walk MarkLinkedReferencesRecursively would run over a
+// transformed tree. That walk does not happen here, because the builtin chain
+// is built from the parse tree below, and no probe reproduces a panic with this
+// call stubbed out. The restoration stays because the remaining exposure is
+// unproven rather than absent. tsgo's own defense against a plugin-built node is ast.IsParseTreeNode,
 // which most EmitResolver reference methods test to bail out early — and a
 // REBUILT container does not trip it. The emit context stamps
 // NodeFlagsSynthesized when its factory creates a node, but ast.updateNode then
@@ -160,16 +186,28 @@ func restoreOriginalDeclarationSymbols(ec *shimprinter.EmitContext, node *shimas
 // EmitTransformPlugins are chained after the caller's transforms in
 // registration order.
 //
+// With no effective transform, ordinary native emission owns bundled output,
+// declarations and build information. This entry still corrects source maps
+// for the source preamble before delivering them to its writer.
+//
 // Because the JavaScript side bypasses tsgo's own emitter, it reproduces that
 // emitter's whole printSourceFile step via PrintFileWithSourceMap: a
-// `sourceMap` / `inlineSourceMap` build emits a `.js.map` (and
-// `//# sourceMappingURL=` trailer) just like a plain build, even when a
-// transform expanded one source line into many; an `emitBOM` build still starts
-// with the byte order mark; and the caller's WriteFile still receives the
-// WriteFileData the emitter would hand it. All non-JavaScript outputs stay
-// delegated to tsgo's normal dts-only emitter so declaration files, declaration
-// maps, and any future declaration-lane outputs are not silently lost by the
-// hand-assembled JS path.
+// `sourceMap` build can emit an external `.js.map` and trailer, while
+// `inlineSourceMap` embeds its map in the trailer instead. Map production follows
+// the printer's source-kind and destination conditions, even when a transform
+// expands source lines; `emitBOM` adds its leading mark. JavaScript WriteFileData
+// carries the fields documented by writePluginEmitOutput, not every field of
+// ordinary native emit. Declarations, declaration maps and build information
+// delegate to the native dts-only pass when that pass is required.
+//
+// @evidence contracts/common.md#principled-implementation Plugin AST transforms share the builtin emit context; parse-tree identity qualifies checker resolution, while native declaration emit retains compiler-owned declaration semantics.
+// @evidence contracts/common.md#clear-and-simple-design JavaScript transformation and declaration emission are separate phases with one buffered output owner and shared diagnostic classification.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Supported factories, original-node ownership, and compiler transformers replace hardcoded import aliases or patched checker functions; noEmitOnError withholds writes until both phases succeed.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain ordering, context integration, maps/BOM, and declaration delegation following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler output paths and native containment checks govern writes; no shell or OS-specific output directory is assumed.
+// @evidence contracts/performance.md#efficient-algorithms Without effective transforms, native whole-program emission and authored source-map correction own output work. Otherwise one original-tree member index precedes the eligible-file loop; each file runs the ordered callback chain and builtin transforms, followed by printing/maps and any native declaration pass. AST size, callback count/work, output bytes, native path checks and declaration work govern cost; callbacks may perform additional traversals.
+// @evidence contracts/performance.md#reuse-equivalent-work Linked program hooks are latched per generation, and the existing checker/resolver serves all per-file transforms instead of constructing independent compiler programs.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The invocation retains original-member references and, under noEmitOnError, all pending output text without a byte cap. Success flushes once; return ends this local ownership, not caller-held output or Program/checker lifetimes. Write failure can leave an already-written prefix; no rollback is promised.
 func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, writeFile shimcompiler.WriteFile) ([]Diagnostic, error) {
   if p == nil || p.TSProgram == nil {
     return nil, errors.New("driver: nil program")
@@ -204,6 +242,34 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
   if result := shimcompiler.HandleNoEmitOnError(context.Background(), p.TSProgram, nil); result != nil {
     return p.pluginEmitDiagnostics("pre-emit checking", result.Diagnostics)
   }
+  hasTransform := false
+  for _, transform := range transforms {
+    if transform != nil {
+      hasTransform = true
+      break
+    }
+  }
+  if !hasTransform {
+    correctSourceMap := p.NewSourceMapCorrector()
+    result, diagnostics, err := p.EmitAllRaw(func(fileName, text string, data *shimcompiler.WriteFileData) error {
+      corrected, err := correctSourceMap(fileName, text)
+      if err != nil {
+        return err
+      }
+      if writeFile != nil {
+        return writeFile(fileName, corrected, data)
+      }
+      return DefaultWriteFile(fileName, corrected)
+    })
+    if err != nil || result == nil {
+      return diagnostics, err
+    }
+    phase := "JavaScript emit"
+    if options.GetEmitDeclarations() {
+      phase = "declaration emit"
+    }
+    return p.pluginEmitDiagnostics(phase, result.Diagnostics)
+  }
   // Snapshot ownership before any transformer runs, including transforms that
   // mutate their input in place or reuse a member from another source file.
   members := make(map[*shimast.Node]struct{})
@@ -216,6 +282,7 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
   // declaration lane, so defer callbacks until both have succeeded. Outside
   // that option keep upstream's emit-despite-errors behavior.
   output := newPluginEmitOutput(writeFile, options.NoEmitOnError.IsTrue())
+  correctSourceMap := p.NewSourceMapCorrector()
   for _, sf := range shimcompiler.GetSourceFilesToEmit(host, nil, false) {
     paths := shimcompiler.GetOutputPathsFor(sf, options, host, false)
     if paths.JsFilePath() != "" && !p.outputEscapesOutDir(paths.JsFilePath()) {
@@ -266,12 +333,11 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
       for _, tr := range shimcompiler.GetScriptTransformers(ec, host, sf) {
         out = tr.TransformSourceFile(out)
       }
-      // Print through the source-map-aware helper so a `sourceMap` /
-      // `inlineSourceMap` build still gets its `.js.map` and sourceMappingURL
-      // trailer, and an `emitBOM` build its leading mark: the hand-assembled
+      // Print through the source-map-aware helper for an external sourceMap or
+      // an inlineSourceMap trailer, and an emitBOM leading mark: the hand-assembled
       // emit pipeline does not run tsgo's emitter, so everything printSourceFile
       // would otherwise do around the printer has to happen here. With maps and
-      // emitBOM off this is the same bare-printer output as before.
+      // emitBOM off the output is the bare printer's.
       printed := shimcompiler.PrintFileWithSourceMap(ec, out.AsNode(), out, options, host, paths.JsFilePath(), paths.SourceMapFilePath())
       // A source-level preamble (e.g. @ttsc/banner linked into a typia host)
       // shifts the map's source coordinates; correct them here too, so the
@@ -279,13 +345,13 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
       // would be if only the utility host's WriteFile patched maps. Covers both
       // the external `.js.map` and an inline base64 map embedded in the JS.
       if p.SourcePreamble != "" {
-        dropLines := strings.Count(p.SourcePreamble, "\n")
-        if adjusted, ok := AdjustEmittedSourceMap(paths.JsFilePath(), printed.JS, dropLines); ok {
-          printed.JS = adjusted
+        var err error
+        if printed.JS, err = correctSourceMap(paths.JsFilePath(), printed.JS); err != nil {
+          return nil, err
         }
         if printed.MapPath != "" {
-          if adjusted, ok := AdjustEmittedSourceMap(printed.MapPath, printed.MapText, dropLines); ok {
-            printed.MapText = adjusted
+          if printed.MapText, err = correctSourceMap(printed.MapPath, printed.MapText); err != nil {
+            return nil, err
           }
         }
       }
@@ -322,9 +388,9 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
   // 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.
+  // a full emit to describe work already done. Other build-information fields
+  // come from this native declaration pass; they are not a separate certificate
+  // of arbitrary plugin reads or of the hand-assembled JavaScript output.
   //
   // ttsc itself never reads build information back (see
   // `shimcompiler.EmitFreshWithBuildInfo`), so this asymmetry costs a ttsc
@@ -341,6 +407,11 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
         }
         return nil
       }
+      corrected, err := correctSourceMap(fileName, text)
+      if err != nil {
+        return err
+      }
+      text = corrected
       return output.write(fileName, text, data)
     },
   })
@@ -356,15 +427,14 @@ func (p *Program) EmitWithPluginTransformers(transforms []PluginTransform, write
 }
 
 // writePluginEmitOutput writes one artifact of the hand-assembled emit, passing
-// the caller's WriteFile the same WriteFileData tsgo's emitter would.
+// the caller's WriteFile the supported WriteFileData fields described below.
 //
 // What this lane can populate, and what it deliberately cannot:
 //
 //   - SourceMapUrlPos: the offset of the `//# sourceMappingURL=` trailer, or -1
 //     when none was written. PrintFileWithSourceMap records it exactly where
 //     printSourceFile does, so a consumer that relocates or rewrites the trailer
-//     works the same on both lanes. This is why a nil data was a real loss and
-//     not merely a cosmetic one.
+//     works the same on both lanes.
 //   - Diagnostics: always empty. The emitter's field carries its accumulated
 //     emitterDiagnostics, which on the JavaScript lane are its own write
 //     failures; here a write failure is returned as an `error` from

package/driver/emit_plugin_output.go

@@ -12,13 +12,37 @@ import (
 // diagnostics remain in the returned slice for structured consumers. Hosts
 // that only check the Go error still reject an incomplete build and display
 // the compiler's code, severity and available source context.
+//
+// @evidence contracts/common.md#principled-implementation Structured diagnostics and the Go error describe the same incomplete native emit, so an error-only host cannot overlook compiler failures.
+// @evidence contracts/common.md#clear-and-simple-design One error value groups diagnostics with the failed phase and declaration-output consequence.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler findings are retained rather than replaced with a success flag or a fixture-specific message.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains the structured and error-only consumer boundary following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This error value stores diagnostic context; renderer and emit owners perform native operations.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Rendering owns traversal; the type stores the error payload.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The error payload coordinates no repeated work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller-owned error retains its diagnostics without acquiring a resource or resident cache.
 type PluginEmitError struct {
-  Diagnostics  []Diagnostic
-  Phase        string
+  // Diagnostics contains the same findings returned by the failed emit.
+  Diagnostics []Diagnostic
+
+  // Phase names the native operation that failed.
+  Phase string
+
+  // Declarations reports whether declaration output may be incomplete.
   Declarations bool
   cwd          string
 }
 
+// Error renders the failed phase and compiler diagnostics for error-only hosts.
+//
+// @evidence contracts/common.md#principled-implementation Error-only consumers receive compiler severity and source context alongside the incomplete-output consequence.
+// @evidence contracts/common.md#clear-and-simple-design A string builder adds phase context then delegates diagnostic formatting to one shared renderer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The real diagnostic slice is rendered without hiding findings behind a generic success or failure marker.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the error-only host use following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Shared diagnostic rendering owns filename presentation; this method owns no native operation.
+// @evidence contracts/performance.md#efficient-algorithms One builder avoids repeated growing-string concatenation; delegated rendering partitions and copies diagnostic references, formats message/source context bytes and native filename presentation, then TrimSpace scans the returned text. Cost includes diagnostic count and rendered content, not only the fixed phase prefix.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each requested error string is rendered independently with no shared-work coordination.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The temporary builder is returned as a string and no resident buffer is retained.
 func (e *PluginEmitError) Error() string {
   var out strings.Builder
   fmt.Fprintf(&out, "driver: native plugin %s failed; build output is incomplete", e.Phase)