@ttsc/wasm 0.30.4 → 0.31.1

package/shim-vendor/shim/core/go.mod

@@ -2,4 +2,9 @@ module github.com/microsoft/typescript-go/shim/core
 
 go 1.26
 
-require github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157
+require github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063
+
+require (
+	github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+)

package/shim-vendor/shim/core/go.sum

@@ -0,0 +1,10 @@
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 h1:nxP4pPoyqOAgX8lYDFCfl3DyKeXErCvSvhcyzwGV9CE=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063 h1:UUVrjTrD+7nkVvkJTjxwA5+SaZ5n1uyAffm2zX2gn+o=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063/go.mod h1:s3yhRRZ7nzSZaiKicku520Tj9Mvewr9y2UtrvpwOmDE=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
+gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=

package/shim-vendor/shim/core/modulekind.go

@@ -7,4 +7,13 @@ package core
 import innercore "github.com/microsoft/typescript-go/internal/core"
 
 // ModuleKind is tsgo's module-format enum (CommonJS, ESNext, NodeNext, ...).
+//
+// @evidence contracts/common.md#principled-implementation A Go alias preserves upstream module-format identity, matching CompilerOptions and emit-host decisions without translating enum values.
+// @evidence contracts/common.md#clear-and-simple-design One compiler discriminator connects configuration and emit format, with constants maintained in the adjacent core shim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Formats remain actual compiler constants rather than hardcoded consumer-specific output choices.
+// @evidence contracts/common.md#meaningful-documentation Native prose gives representative formats and package context explains the emit-host consumer.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type ModuleKind = innercore.ModuleKind

package/shim-vendor/shim/core/shim.go

@@ -13,32 +13,119 @@ import (
 
 // CompilerOptions holds the parsed tsconfig compiler options passed to the
 // TypeScript-Go program host.
+//
+// @evidence contracts/common.md#principled-implementation A Go alias retains the parsed option fields and upstream tristate types exactly, preserving unset versus explicit false in compiler configuration.
+// @evidence contracts/common.md#clear-and-simple-design Hosts pass the compiler's own options value instead of maintaining another option schema and conversion layer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Configuration remains caller/compiler data, with no consumer-specific option overrides in this alias.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies parsed tsconfig provenance and the Program-host consumer, separate from these tags.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type CompilerOptions = innercore.CompilerOptions
 
 // JsxEmit is the parsed compilerOptions.jsx mode.
+//
+// @evidence contracts/common.md#principled-implementation The alias preserves the upstream JSX mode discriminator and the values forwarded by this package's JsxEmit constants.
+// @evidence contracts/common.md#clear-and-simple-design One enum identity serves parsed options and compiler consumers without translating JSX modes.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Modes use actual compiler constants rather than guessed strings or consumer-selected numeric values.
+// @evidence contracts/common.md#meaningful-documentation The comment names the configuration field this discriminator represents.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type JsxEmit = innercore.JsxEmit
 
 // ModuleResolutionKind selects TypeScript-Go's module resolver.
+// The alias also retains unknown and deprecated parsing values; retaining a
+// discriminator does not certify that every value can run a resolver.
+//
+// @evidence contracts/common.md#principled-implementation Aliasing the upstream enum preserves its declared resolver-selection and parsing values exactly in CompilerOptions. Runtime admission and dispatch remain with compiler owners, including refusal of unsupported values.
+// @evidence contracts/common.md#clear-and-simple-design Resolver selection remains one compiler discriminator instead of a parallel shim policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Selection uses upstream constants without guessing a resolver from a consumer name or host OS.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies resolver selection rather than merely repeating the type 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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type ModuleResolutionKind = innercore.ModuleResolutionKind
 
-// ResolutionMode is the CommonJS or ESM lookup mode for one module use.
+// ResolutionMode represents None, CommonJS or ESM lookup for one module use.
+// Upstream aliases ModuleKind for this role; it is not a distinct Go type or a
+// validated three-value set. Per-use lookup differs from project resolver policy.
+//
+// @evidence contracts/common.md#principled-implementation The alias preserves per-use CommonJS/ESM discrimination independently from the project's overall module resolution strategy.
+// @evidence contracts/common.md#clear-and-simple-design The upstream alias exposes the per-use role independently from ModuleResolutionKind while preserving its actual ModuleKind type identity and None/CommonJS/ESM constants.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Modes remain compiler facts rather than a file-extension heuristic in the shim.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies per-use scope, None and CommonJS/ESM constants, the actual upstream type alias and absence of value validation.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type ResolutionMode = innercore.ResolutionMode
 
 // Tristate is a three-valued boolean: TSFalse, TSTrue, or TSUnknown. Used by
 // CompilerOptions fields that can be explicitly unset.
+//
+// @evidence contracts/common.md#principled-implementation Go alias identity retains upstream false, true and unknown values, so a boolean conversion cannot erase the distinction used during option merging.
+// @evidence contracts/common.md#clear-and-simple-design One three-valued representation serves compiler options instead of separate presence and boolean fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown is retained as a real compiler state rather than being silently coerced to a desired default.
+// @evidence contracts/common.md#meaningful-documentation Native prose names the three values and their configuration use before the acknowledgment block.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type Tristate = innercore.Tristate
 
-// TextPos is a zero-based byte offset into a source file's text.
+// TextPos is a signed 32-bit byte coordinate. Source offsets are zero-based;
+// negative values also represent absent positions for synthesized nodes.
+//
+// @evidence contracts/common.md#principled-implementation The alias preserves the compiler's integer byte-coordinate representation; it does not reinterpret offsets as UTF-16 character positions.
+// @evidence contracts/common.md#clear-and-simple-design A single compiler coordinate type connects source ranges and line starts without a unit-conversion wrapper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Byte offsets are retained without guessed JavaScript character conversion.
+// @evidence contracts/common.md#meaningful-documentation The declaration states signed 32-bit storage, zero-based byte units and negative synthetic-position meaning.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type TextPos = innercore.TextPos
 
 // ECMALineStarts holds the byte offset of every source line the compiler
 // recognizes under ECMAScript's line-terminator rules.
+//
+// @evidence contracts/common.md#principled-implementation The alias keeps upstream line-start storage and byte-coordinate identity, matching the ComputeECMALineStarts result consumed by compiler location logic.
+// @evidence contracts/common.md#clear-and-simple-design Line positions use the compiler's existing representation rather than another indexed line model.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Source line starts follow compiler semantics rather than a newline split that discards ECMAScript terminators.
+// @evidence contracts/common.md#meaningful-documentation Native prose states byte offsets and the language's line-terminator model.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type ECMALineStarts = innercore.ECMALineStarts
 
-// TextRange is a half-open [Pos, End) byte range inside a source file.
+// TextRange is a half-open [Pos, End) byte range, or an undefined range with
+// negative endpoints for a synthesized node.
+//
+// @evidence contracts/common.md#principled-implementation Aliasing the upstream range preserves its two byte endpoints and methods, including the undefined range supplied for synthesized nodes.
+// @evidence contracts/common.md#clear-and-simple-design One upstream interval representation serves constructors and AST users without a competing span type.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Positions stay compiler values without fabricating a source interval for a synthetic node.
+// @evidence contracts/common.md#meaningful-documentation Native prose states half-open endpoints and byte units; UndefinedTextRange documents synthesized-node absence.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type TextRange = innercore.TextRange
 
 // ScriptKind identifies the syntactic flavour of a source file.
+//
+// @evidence contracts/common.md#principled-implementation The upstream alias preserves source-language discrimination used by parsing, including TS, JS, JSX/TSX and JSON constants.
+// @evidence contracts/common.md#clear-and-simple-design Parsed source flavour uses one compiler enum rather than a shim string-to-language mapper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The bridge forwards upstream kinds without special-casing a named file or package.
+// @evidence contracts/common.md#meaningful-documentation The comment states syntactic source flavour and adjacent constant comments identify the supported family.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type ScriptKind = innercore.ScriptKind
 
 const (
@@ -95,12 +182,47 @@ const (
 )
 
 // Version reports the TypeScript compiler version typescript-go implements, in
-// the same form `tsc --version` prints. A graph snapshot publishes it so a
-// consumer can tell which checker resolved the facts it is reading.
+// upstream's compiled version-string form, which can be overridden at link
+// time. A graph snapshot publishes this semantic version; it does not identify
+// the precise checker revision or certify executable/artifact identity.
+//
+// @evidence contracts/common.md#principled-implementation Direct delegation returns the version the pinned compiler implements, matching the checker that produced the consumer's semantic facts.
+// @evidence contracts/common.md#clear-and-simple-design One accessor supplies upstream version identity without parsing manifests or inferring release metadata.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The answer comes from the compiler rather than a hardcoded ttsc package version.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes compiler version from host release and explains the graph consumer's provenance need.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned string borrows backing storage owned by upstream's process-lifetime compiled version variable. No new file handle, independent buffer or historical result registry is acquired here; callers can retain the string without making this wrapper the version-state owner.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream owns the direct compiled-string projection. This bridge chooses no independent version computation, parsing or metadata traversal.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Static compiled version state belongs to upstream; this accessor coordinates no completed/in-flight version producer or cache invalidation policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This accessor reads compiled version metadata without native filesystem, path-identity or process operations. It does not infer the selected executable's identity or OS capabilities.
 func Version() string { return innercore.Version() }
 
+// ApplyDebugStackLimit applies a positive TS_GO_DEBUG_STACK_LIMIT byte count
+// to this process's Go runtime. Missing, invalid or nonpositive values do nothing.
+// Parsing uses the runtime's int width. A successful call changes process-wide
+// stack policy; this wrapper does not restore its previous setting.
+//
+// @evidence contracts/common.md#principled-implementation Upstream parsing and runtime.SetMaxStack preserve the documented opt-in process-wide limit and invalid-value no-op.
+// @evidence contracts/common.md#clear-and-simple-design One explicit operation leaves environment parsing and runtime policy with the compiler owner.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The explicit upstream operation changes the process-wide stack limit only when its environment input requests a positive limit; no consumer-specific policy is substituted.
+// @evidence contracts/common.md#meaningful-documentation Native prose states byte units, process scope and the three no-op conditions.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream may persist a new process-wide runtime stack limit after parsing the environment. No file handle or independent cache is acquired by this bridge, but absence of those resources is not absence of lasting policy state. The runtime and caller own that setting and any later replacement; this adapter provides no scoped restoration.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream owns environment lookup, integer parsing over the supplied value bytes and runtime policy mutation. This direct bridge chooses no independent lookup/parser/stack-management algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Environment lookup and the explicit runtime setter are not coordinated as completed or in-flight shared work here; the runtime owns its policy state, and this bridge provides no separate producer or memoized setting.
+// @evidence contracts/portability.md#os-neutral-implementation Supported os.Getenv and runtime/debug.SetMaxStack obtain the actual process environment and change this Go runtime's policy without OS-name branches or shell interpretation. strconv.Atoi admits only a positive value representable by the runtime's int width; the setting is process-wide rather than a per-call platform capability certificate.
+func ApplyDebugStackLimit() { innercore.ApplyDebugStackLimit() }
+
 // TypeScriptVersionSatisfiesRange reports whether the compiler's own version
 // satisfies a typesVersions range under TypeScript-Go's semver grammar.
+// Invalid range or compiler-version syntax returns false.
+//
+// @evidence contracts/common.md#principled-implementation Both range and compiler version use upstream semver parsing; the parsed range tests that version, and invalid parsing returns false rather than implying satisfaction.
+// @evidence contracts/common.md#clear-and-simple-design One predicate owns range parsing and testing, leaving compiler version production with Version and grammar with upstream semver.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts typesVersions matching uses real compiler version and parser semantics rather than consumer names or lexicographic version guesses.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies typesVersions, the upstream grammar and invalid-syntax refusal.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream parsing allocates alternative/comparator and version-component storage for this invocation, potentially retaining substrings until its local values become unreachable. Only a boolean escapes this function; global compiler-version and regex state remain upstream-owned. No independent parse-result history or native handle is retained here, and no fixed input/alternative count cap is imposed.
+// @evidence contracts/performance.md#efficient-algorithms Parse the range once, return early when invalid, then parse the actual compiler version once and test it. Delegated regex/tokenization, component parsing and short-circuit alternative/comparator tests scale with supplied range/version text and parsed population; the wrapper's few calls do not make this fixed-cost work.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate coordinates no completed/in-flight range-result cache; parsing and matching remain invocation-local while upstream owns static regex and compiler-version state. Caller owners decide whether a result remains equivalent for unchanged range and actual compiler identity.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Matching reads supplied range text and the compiled upstream version string; it performs no native filesystem, path-identity or process operation. Compiler-version metadata is semantic input, not an OS capability query.
 func TypeScriptVersionSatisfiesRange(text string) bool {
   versionRange, ok := innersemver.TryParseVersionRange(text)
   if !ok {
@@ -112,12 +234,41 @@ func TypeScriptVersionSatisfiesRange(text string) bool {
 
 // ComputeECMALineStarts applies the compiler's LF, CRLF, CR, LS, and PS line
 // model to UTF-8 source text.
+//
+// @evidence contracts/common.md#principled-implementation Direct delegation applies the compiler's ECMAScript line-terminator scan and returns its byte offsets, preserving CRLF pairing and non-ASCII terminators.
+// @evidence contracts/common.md#clear-and-simple-design One text-to-line-start adapter reuses the compiler model without a separate line scanner.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The implementation does not approximate compiler lines by splitting only on LF or guessing UTF-16 offsets.
+// @evidence contracts/common.md#meaningful-documentation Native prose enumerates LF, CRLF, CR, LS and PS and identifies UTF-8 source units.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream allocates and may grow a line-start backing array; the returned slice keeps that storage reachable under the caller's lifetime. Initial capacity counts LF bytes, so other terminators can require growth. The bridge keeps no independent history cache or handle and imposes no fixed source/line-count cap.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The pinned compiler owns the LF-capacity count and ECMAScript byte/rune scan, both over source text, plus line-array append/growth. This direct bridge selects no independent scanner or storage algorithm; fixed-step wrapper syntax does not remove those input-size costs.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This bridge does not coordinate a source-version cache or completed/in-flight index producer; compiler and caller owners decide whether an already computed line index can be reused for equivalent text.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation ComputeECMALineStarts computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func ComputeECMALineStarts(text string) ECMALineStarts {
   return innercore.ComputeECMALineStarts(text)
 }
 
-// NewTextRange constructs a closed/open [pos, end) text range.
+// NewTextRange constructs a half-open [pos, end) byte range. Endpoints must fit
+// signed 32-bit TextPos storage; the constructor does not validate ordering or
+// source bounds.
+//
+// @evidence contracts/common.md#principled-implementation The upstream constructor casts integer endpoints into signed 32-bit TextPos storage, preserving representable values; range ordering, representability and source bounds remain the caller's responsibility.
+// @evidence contracts/common.md#clear-and-simple-design One constructor supplies the native range without a separate normalization or coordinate-conversion policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Endpoints are not clamped to manufacture an apparently valid range for a consumer.
+// @evidence contracts/common.md#meaningful-documentation Native prose states half-open byte endpoints, signed 32-bit representability and absence of constructor validation, separated from implementation grounds.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources NewTextRange acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The pinned constructor owns the two endpoint casts and range representation. This direct bridge chooses no separate normalization, traversal or validation algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This scalar range adapter is not a completed/in-flight work producer or cache coordinator; caller operations own reuse of ranges associated with source versions.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation NewTextRange computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func NewTextRange(pos, end int) TextRange { return innercore.NewTextRange(pos, end) }
 
 // UndefinedTextRange marks synthesized AST nodes that do not map to source.
+//
+// @evidence contracts/common.md#principled-implementation Delegation returns the compiler's own undefined-range sentinel, preserving its meaning for synthesized rather than source-backed nodes.
+// @evidence contracts/common.md#clear-and-simple-design A named sentinel constructor distinguishes missing source provenance from ordinary NewTextRange intervals.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Synthetic nodes receive upstream absence metadata rather than fabricated source coordinates.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains synthesized-node provenance and why an undefined interval exists.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources UndefinedTextRange acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream owns the scalar undefined-endpoint representation. This direct bridge chooses no independent range algorithm, source traversal or coordinate validation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The sentinel adapter coordinates no completed/in-flight work producer or cache; it supplies scalar absence metadata for caller-owned AST operations.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation UndefinedTextRange computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func UndefinedTextRange() TextRange { return innercore.UndefinedTextRange() }

package/shim-vendor/shim/diagnosticwriter/go.mod

@@ -2,4 +2,13 @@ module github.com/microsoft/typescript-go/shim/diagnosticwriter
 
 go 1.26
 
-require github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157
+require github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063
+
+require (
+	github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
+	github.com/zeebo/xxh3 v1.1.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
+)

package/shim-vendor/shim/diagnosticwriter/go.sum

@@ -0,0 +1,20 @@
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 h1:nxP4pPoyqOAgX8lYDFCfl3DyKeXErCvSvhcyzwGV9CE=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
+github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063 h1:UUVrjTrD+7nkVvkJTjxwA5+SaZ5n1uyAffm2zX2gn+o=
+github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063/go.mod h1:s3yhRRZ7nzSZaiKicku520Tj9Mvewr9y2UtrvpwOmDE=
+github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
+github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
+golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
+gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
+gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=

package/shim-vendor/shim/diagnosticwriter/lint.go

@@ -25,7 +25,17 @@ import (
 )
 
 // LintCategory selects warning vs error rendering. Warnings render yellow,
-// errors render red — the exit-code decision lives in the caller.
+// errors render red; the exit-code decision lives in the caller.
+// Any value other than LintCategoryError maps to warning.
+//
+// @evidence contracts/common.md#principled-implementation Separate category constants preserve error versus warning; Category and IsError share the exact error discriminator, so display and error counting agree even for other integer values.
+// @evidence contracts/common.md#clear-and-simple-design One category value drives both rendering and caller error classification without coupling the diagnostic to a process exit.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Category constants express the renderer contract, not severity guesses based on message text or a rule's consumer.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies display categories, caller-owned exit decisions and the non-error fallback.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type LintCategory int
 
 const (
@@ -38,6 +48,15 @@ const (
 // caller's contract says they point inside the current file. Reversed and
 // zero-width ranges select one byte when one exists at pos; EOF and empty-file
 // ranges remain zero-width instead of manufacturing a byte past the source.
+//
+// @evidence contracts/common.md#principled-implementation Clamping both byte endpoints into [0, source length] and extending a nonpositive span only before EOF establishes 0 <= pos <= end <= length; nil source yields an empty project-wide span.
+// @evidence contracts/common.md#clear-and-simple-design One boundary normalizer owns producer-range sanitation for every NewLintDiagnostic instead of requiring each renderer method to repair offsets.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Clamping addresses untrusted producer coordinates against the actual source length; it does not substitute canned diagnostic ranges or hide an out-of-file byte.
+// @evidence contracts/common.md#meaningful-documentation Native prose states half-open units, why sanitation belongs at the producer boundary, and the reversed/EOF/empty-file effects.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources NormalizeLintRange acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidence contracts/performance.md#efficient-algorithms Reading the existing source text length and clamping two scalar endpoints takes constant work and space independent of source bytes; selecting one byte before EOF avoids scanning text or allocating a replacement span.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This scalar sanitizer owns no cross-request producer, cache or in-flight coordinator; construction stores its result so renderer accessors do not repeat sanitation for the same diagnostic.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation NormalizeLintRange computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func NormalizeLintRange(file *ast.SourceFile, pos, end int) (int, int) {
   if file == nil {
     return 0, 0
@@ -63,9 +82,22 @@ func NormalizeLintRange(file *ast.SourceFile, pos, end int) (int, int) {
 }
 
 // LintDiagnostic is a public, plugin-emittable diagnostic shaped like the
-// `internal/diagnosticwriter.Diagnostic` interface. The internal type is
-// unexported, so this is the only way to mix lint output with tsgo's own
-// diagnostics in a single render pass.
+// `internal/diagnosticwriter.Diagnostic` interface. The upstream interface lives
+// in an internal package that outside plugin modules cannot import directly.
+// This public implementation lets their findings share the compiler renderer.
+//
+// The source file is retained, not copied; its text must remain the version the
+// diagnostic range describes. Stored-field accessors require a nonnil
+// receiver; File, Message and the empty-metadata accessors are nil-safe.
+//
+// @evidence contracts/common.md#principled-implementation Private source, normalized byte endpoints, severity and message implement the upstream Diagnostic methods without losing project-wide nil source or already-localized lint prose.
+// @evidence contracts/common.md#clear-and-simple-design One immutable-by-public-API value implements the renderer boundary, with construction owning range validation and accessors supplying stored facts.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Lint findings enter the same formatter through an explicit interface implementation rather than modifying upstream diagnostics or injecting global output.
+// @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain the internal-package import boundary, retained source version and nil-receiver limits; public accessors document units and optional metadata.
+// @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.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type LintDiagnostic struct {
   file     *ast.SourceFile
   pos      int
@@ -76,8 +108,20 @@ type LintDiagnostic struct {
 }
 
 // NewLintDiagnostic builds a lint diagnostic anchored at [pos, end) in the
-// supplied source file. `code` shows up in the rendered banner — the
+// supplied source file. `code` shows up in the rendered banner; the
 // convention is to give each rule its own stable integer.
+// A nil file creates a project-wide message with an empty range.
+// The returned value borrows the source file and message backing storage;
+// it does not validate code uniqueness, category membership or localization.
+//
+// @evidence contracts/common.md#principled-implementation Construction normalizes the caller's byte span before storing the supplied source identity, code, category and message; nil source retains project-wide absence, while code stability and final prose remain producer responsibilities.
+// @evidence contracts/common.md#clear-and-simple-design One constructor establishes the range invariant for the private fields; renderer accessors need no repeated sanitation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The value contains actual producer findings; stable codes identify rules rather than synthesizing expected compiler messages.
+// @evidence contracts/common.md#meaningful-documentation Native prose states half-open anchoring, code identity convention and nil-file meaning, with range normalization explained on its owner.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Each returned record retains the borrowed source graph and message backing storage until its consumers release their references; construction copies scalar coordinates and metadata, not source or message bytes, and opens no handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Range sanitation belongs to NormalizeLintRange; this constructor only transfers its normalized scalar result and supplied fields into the returned record, without an independent traversal or lookup strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This constructor does not own a cache, keyed producer or request coordinator; the caller decides whether existing diagnostic records can be reused for its source version and finding.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation NewLintDiagnostic computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func NewLintDiagnostic(file *ast.SourceFile, pos, end int, code int32, category LintCategory, message string) *LintDiagnostic {
   pos, end = NormalizeLintRange(file, pos, end)
   return &LintDiagnostic{
@@ -90,6 +134,17 @@ func NewLintDiagnostic(file *ast.SourceFile, pos, end int, code int32, category
   }
 }
 
+// File supplies the retained source, or nil for a project-wide/nil diagnostic.
+// Returning an untyped nil avoids a non-nil interface containing a nil pointer.
+//
+// @evidence contracts/common.md#principled-implementation The explicit nil branch preserves absent source at the interface boundary; present files retain their original compiler identity and text.
+// @evidence contracts/common.md#clear-and-simple-design One accessor owns pointer-to-interface absence conversion without a wrapper file representation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing source remains absent rather than a fabricated file used to satisfy the renderer.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains retained provenance, project-wide absence and the Go typed-nil interface consequence.
+// @evidence contracts/performance.md#bound-retention-and-release-resources A nonnil returned interface borrows the stored SourceFile and can keep its source/AST/semantic graph reachable under the caller's lifetime. Nil cases carry no source. The diagnostic and compiler owners retain their existing graph ownership; this accessor allocates no independent source copy or history registry and does not release that graph on return.
+// @evidence contracts/performance.md#efficient-algorithms Two nil checks select true interface absence or the existing source pointer; no source-content scan, wrapper file allocation or coordinate conversion is needed.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Existing source identity belongs to the diagnostic/compiler owners; this accessor coordinates no completed/in-flight source producer or source-version cache.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation File computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (d *LintDiagnostic) File() inner.FileLike {
   if d == nil || d.file == nil {
     return nil
@@ -97,11 +152,66 @@ func (d *LintDiagnostic) File() inner.FileLike {
   return d.file
 }
 
-func (d *LintDiagnostic) Pos() int    { return d.pos }
-func (d *LintDiagnostic) End() int    { return d.end }
-func (d *LintDiagnostic) Len() int    { return d.end - d.pos }
+// Pos returns the normalized inclusive UTF-8 byte offset.
+//
+// @evidence contracts/common.md#principled-implementation Reading the constructor-normalized start preserves the source interval used by the renderer; the receiver must be non-nil.
+// @evidence contracts/common.md#clear-and-simple-design The accessor supplies one stored endpoint without reinterpreting coordinates.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The offset remains producer/source data rather than a guessed JavaScript character position.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies normalized origin and byte units; the type states the non-nil receiver premise.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Pos acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This accessor projects the constructor-normalized scalar start; it chooses no independent range-validation, source traversal or coordinate-conversion algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Stored endpoint state belongs to the diagnostic owner; this accessor coordinates no completed/in-flight producer or source-version cache.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Pos computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func (d *LintDiagnostic) Pos() int { return d.pos }
+
+// End returns the normalized exclusive UTF-8 byte offset.
+//
+// @evidence contracts/common.md#principled-implementation Reading the constructor-normalized end retains the half-open interval and its source-length bound; the receiver must be non-nil.
+// @evidence contracts/common.md#clear-and-simple-design One endpoint accessor keeps interval facts distinct from derived length.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The end is not extended past EOF to invent a visible diagnostic byte.
+// @evidence contracts/common.md#meaningful-documentation Native prose states normalized exclusive endpoint and byte units, with receiver requirements on the type.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources End acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This accessor projects the endpoint already normalized by construction; it chooses no independent range-validation, coordinate-conversion or traversal algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Stored endpoint state belongs to the diagnostic owner; this accessor coordinates no completed/in-flight producer or cache invalidation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation End computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func (d *LintDiagnostic) End() int { return d.end }
+
+// Len returns the normalized span length in UTF-8 bytes, including zero at EOF.
+//
+// @evidence contracts/common.md#principled-implementation End minus start is a nonnegative byte length because construction establishes ordered endpoints within the source; the receiver must be non-nil.
+// @evidence contracts/common.md#clear-and-simple-design Deriving length from the two stored endpoints avoids another mutable field that could diverge from them.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Zero-width spans remain real absence of covered bytes rather than a fabricated length beyond the source.
+// @evidence contracts/common.md#meaningful-documentation Native prose states byte length and the EOF zero-width case before acknowledgment tags.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Len acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidence contracts/performance.md#efficient-algorithms Subtract the two constructor-normalized scalar endpoints directly; no source scan, repeated sanitation or byte-to-character conversion is required for the stored span length.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Stored range state belongs to the diagnostic owner; this scalar derived-value query coordinates no completed/in-flight producer or source-version cache.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Len computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func (d *LintDiagnostic) Len() int { return d.end - d.pos }
+
+// Code returns the producer-supplied diagnostic identifier unchanged.
+// The receiver must be nonnil; uniqueness and stability are producer policy.
+//
+// @evidence contracts/common.md#principled-implementation The stored int32 code passes through unchanged, retaining the rule identity used by formatter banners and consumers.
+// @evidence contracts/common.md#clear-and-simple-design One accessor exposes producer identity independently from severity and message presentation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Codes are supplied by the producer rather than inferred from expected message text.
+// @evidence contracts/common.md#meaningful-documentation Native prose names stable producer identity; construction explains the per-rule convention.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Code acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This accessor projects a stored scalar chosen by the producer; it chooses no independent code lookup, validation, conversion or traversal algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Stored diagnostic identity belongs to the producer; this accessor coordinates no completed/in-flight computation or cache invalidation policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Code computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (d *LintDiagnostic) Code() int32 { return d.code }
 
+// Category translates the exact error discriminator; every other value is warning.
+// The receiver must be nonnil; stored category values are not validated here.
+//
+// @evidence contracts/common.md#principled-implementation The same LintCategoryError comparison used by IsError maps stored categories to upstream error/warning values, keeping rendering and failure counting consistent.
+// @evidence contracts/common.md#clear-and-simple-design One translation boundary adapts the public lint category to the internal formatter enum.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit category data determines severity without message heuristics or consumer-specific reclassification.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the exact discriminator and fallback, rather than implying arbitrary integers form validated enum values.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Category acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidence contracts/performance.md#efficient-algorithms One exact scalar comparison selects the upstream error category, with warning as the fallback; no message/path scan, lookup table or allocation is needed for translation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This stored-category projection coordinates no completed/in-flight producer or cache; the diagnostic owner controls the category value and its lifetime.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Category computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (d *LintDiagnostic) Category() diagnostics.Category {
   if d.category == LintCategoryError {
     return diagnostics.CategoryError
@@ -109,11 +219,55 @@ func (d *LintDiagnostic) Category() diagnostics.Category {
   return diagnostics.CategoryWarning
 }
 
-func (d *LintDiagnostic) Localize(_ locale.Locale) string        { return d.message }
-func (d *LintDiagnostic) MessageChain() []inner.Diagnostic       { return nil }
+// Localize returns the producer's already-localized message; locale is unused.
+// The receiver must be nonnil. The producer supplies final prose; this method
+// does not verify its language or perform translation.
+//
+// @evidence contracts/common.md#principled-implementation Returning stored prose preserves the producer's chosen message without applying another locale transformation to an already-localized value.
+// @evidence contracts/common.md#clear-and-simple-design One formatter adapter supplies stored prose while message creation stays with the rule.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The message is not replaced by a canned compiler diagnostic or inferred translation.
+// @evidence contracts/common.md#meaningful-documentation Native prose explicitly states already-localized input and ignored locale semantics.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned string borrows the stored message backing bytes, which a caller can keep reachable after the diagnostic's own lifetime. No independent message copy, native handle or historical localization registry is acquired by this accessor; the producer and caller own those bytes and retention.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This accessor projects stored text without scanning, translating or validating it; the producer owns message construction and localization algorithms.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Already-produced message state belongs to the diagnostic owner; this accessor coordinates no completed/in-flight translation producer or locale-keyed cache.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Localize computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func (d *LintDiagnostic) Localize(_ locale.Locale) string { return d.message }
+
+// MessageChain returns nil because this diagnostic contains one flat message.
+//
+// @evidence contracts/common.md#principled-implementation Nil represents the absent chain in the upstream interface; the value stores a flat message rather than structured children.
+// @evidence contracts/common.md#clear-and-simple-design The adapter states its flat-message capability without an unused child-diagnostic hierarchy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing structured metadata remains absent rather than manufactured chain nodes.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains the absence and its representation premise.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources MessageChain acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This capability projection supplies absent structured metadata and chooses no child-graph construction, traversal or formatting algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work No message-chain computation or completed/in-flight producer is coordinated here; structured metadata is absent in this diagnostic representation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation MessageChain computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func (d *LintDiagnostic) MessageChain() []inner.Diagnostic { return nil }
+
+// RelatedInformation returns nil; this value carries no auxiliary diagnostics.
+//
+// @evidence contracts/common.md#principled-implementation Nil preserves the absence of related diagnostics under the upstream formatter interface.
+// @evidence contracts/common.md#clear-and-simple-design A focused flat diagnostic does not acquire an unused related-information store.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Auxiliary source sites are not fabricated from message spelling.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the unsupported auxiliary metadata capability directly.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources RelatedInformation acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This capability projection supplies absent auxiliary metadata and chooses no related-site construction, source lookup or diagnostic-graph traversal algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work No auxiliary-diagnostic computation or completed/in-flight producer is coordinated here; related information is absent in this flat representation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation RelatedInformation computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (d *LintDiagnostic) RelatedInformation() []inner.Diagnostic { return nil }
 
 // Message returns the already-localized lint message.
+// It returns an empty string for a nil receiver.
+//
+// @evidence contracts/common.md#principled-implementation The accessor preserves producer prose on present diagnostics and supplies the documented empty absence value for a nil receiver.
+// @evidence contracts/common.md#clear-and-simple-design The public string accessor is separate from the locale-shaped formatter method, while both use the same stored message.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Nil does not cause a fabricated finding or a guessed diagnostic message.
+// @evidence contracts/common.md#meaningful-documentation Native prose names already-localized content and the nil-receiver result.
+// @evidence contracts/performance.md#bound-retention-and-release-resources A present receiver returns borrowed message backing bytes that callers may retain after return; the nil branch returns the empty string. The accessor creates no independent text copy, native handle or historical message registry, and producer/caller owners determine the stored text's lifetime.
+// @evidence contracts/performance.md#efficient-algorithms One receiver nil check chooses empty absence or a stored string projection; no message scan, formatting, localization or copy is required here.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Stored producer text belongs to the diagnostic owner; this accessor coordinates no completed/in-flight message computation or localization cache.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Message computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (d *LintDiagnostic) Message() string {
   if d == nil {
     return ""
@@ -123,12 +277,36 @@ func (d *LintDiagnostic) Message() string {
 
 // IsError reports whether the diagnostic should fail the build. Lint plugins
 // use this to compute their exit code separately from the renderer.
+// The receiver must be nonnil; only the exact error discriminator is true.
+//
+// @evidence contracts/common.md#principled-implementation The exact error-category comparison matches Category's upstream mapping, so callers count the same diagnostics that render as errors.
+// @evidence contracts/common.md#clear-and-simple-design A boolean category query leaves process exit-code policy with the caller instead of embedding it in a rendered diagnostic.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Stored category data determines failure classification without matching consumer or message names.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains caller-owned exit decisions and the separation from rendering.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IsError acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidence contracts/performance.md#efficient-algorithms One exact stored-category comparison supplies the scalar classification without scanning message/path text or allocating state; caller build policy is not recomputed here.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Diagnostic category state belongs to its producer; this predicate coordinates no completed/in-flight work or cross-version result cache.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsError computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func (d *LintDiagnostic) IsError() bool { return d.category == LintCategoryError }
 
 // FormatMixedDiagnostics renders raw tsgo diagnostics and lint diagnostics
 // together with TypeScript-style colors and source context, followed by the
 // `Found N errors` summary. Returns the count of error-level diagnostics so
 // callers can decide on an exit code.
+// Nil entries from either producer are ignored. Source files must remain the
+// versions described by their diagnostic byte ranges throughout rendering.
+// The writer and nonnil diagnostic graphs must satisfy upstream formatting
+// premises. Individual write errors are not returned; the count classifies
+// findings and is not a successful-output-delivery receipt.
+//
+// @evidence contracts/common.md#principled-implementation Upstream AST adapters and the lint interface implementation share one renderer; exact category comparisons count errors, and deterministic source/range/code/message ordering preserves both producers' complete findings.
+// @evidence contracts/common.md#clear-and-simple-design One mixed rendering entry owns filtering, ordering and summary composition, with a private comparator centralizing tie-breaking and upstream owning snippet formatting.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Real findings flow through a caller-supplied writer rather than a swapped global stream; nil filtering does not drop present findings or manufacture successful diagnostics.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains mixed source context, returned error count, nil-entry handling and retained source-version requirements before these tags.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The combined array, AST adapters, comparator-created message/related arrays and formatter/summary state are invocation-local and borrow diagnostic/source graphs. Writer buffers and source-owner caches can survive under their owners after return; this renderer does not close the writer, keep a historical batch registry or impose fixed byte/population limits. Unreferenced local state is eligible for collection rather than explicitly reclaimed at the last write.
+// @evidence contracts/performance.md#efficient-algorithms Collect and count nonnil diagnostics, then sort by source/range/code/category and localized/nested content before rendering and summary construction. Sorting adds comparison-dependent work over path/message bytes and recursive diagnostic graphs; upstream snippets, location conversion, summary grouping/sort and writer operations add further work. A single formatting call does not remove those scans or make the total linear in diagnostic count.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This renderer coordinates no completed/in-flight formatted-batch cache. The combined array is rebuilt per invocation; upstream/source owners manage reusable localization or position state, while output reuse for an equivalent diagnostic/context snapshot belongs to callers.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This renderer sorts diagnostic data and delegates display-path formatting using supplied cwd; it does not establish native file identity or select an executable/filesystem capability. The supplied writer's native destination and lifetime belong to its caller, and display spelling is not certified as a case-policy answer.
 func FormatMixedDiagnostics(
   output io.Writer,
   astDiags []*ast.Diagnostic,