ttsc 0.33.1 → 0.34.0

package/targets/7.1/bridge/compiler/incremental.go

@@ -0,0 +1,185 @@
+// gen_shims:hand-maintained
+//
+// Parts of tsgo's own incremental engine (`tsc --incremental` semantics),
+// exposed from internal/execute/incremental for the two things a ttsc host
+// needs from it:
+//
+//   - the reference graph, so transform envelopes can carry the same
+//     language-semantic input bound the compiler itself uses for invalidation:
+//     per-file direct resolved references and the files that contribute to the
+//     global scope;
+//   - the build-information emit, so a host that constructs its Program
+//     in-process still writes the `.tsbuildinfo` an `incremental` or
+//     `composite` project asked for.
+package compiler
+
+import (
+  "context"
+  "time"
+  _ "unsafe"
+
+  innerast "github.com/microsoft/TypeScript/tsc/internal/ast"
+  "github.com/microsoft/TypeScript/tsc/internal/collections"
+  innercompiler "github.com/microsoft/TypeScript/tsc/internal/compiler"
+  innertsoptions "github.com/microsoft/TypeScript/tsc/internal/tsoptions"
+  "github.com/microsoft/TypeScript/tsc/internal/tspath"
+
+  // Imported for EmitFreshWithBuildInfo below, and for the linknamed symbols
+  // further down: compiling the package into every shim consumer is what makes
+  // those references resolve.
+  "github.com/microsoft/TypeScript/tsc/internal/execute/incremental"
+)
+
+// EmitFreshWithBuildInfo emits through a new upstream incremental wrapper
+// around the supplied checked Program, with no previous wrapper/snapshot.
+// Its build-information format and candidate location come from upstream
+// snapshot serialization and outputpaths.GetBuildInfoFileName.
+//
+// This is the emit half of `tsc.go::performIncrementalCompilation`, which the
+// tsgo CLI takes whenever `CompilerOptions.IsIncremental()`. A host that builds
+// its Program in-process (ttsc's driver, and therefore every plugin sidecar
+// emitting through it) never reaches that CLI path, so without this the build
+// information is silently dropped even though the options parsed cleanly.
+//
+// "Fresh" in EmitFreshWithBuildInfo means no previous snapshot is supplied.
+// When upstream incremental-state tracking is enabled, initial construction
+// tracks loaded files and makes their applicable output pending rather than
+// reusing prior emit signatures or diagnostics. TargetSourceFile still selects
+// single-file emission; noEmit/noEmitOnError, cancellation, blocked output and
+// write failure retain their upstream behavior. A whole-program eligible emit
+// attempts pending build info, but a record is not guaranteed on every call.
+// The supplied Program and context must be valid for this emit round. A plugin's
+// output is not a pure function of the source text a build info records — it
+// also depends on the plugin binary, its config file, and its contributors —
+// so reusing a previous snapshot to skip a file would serve stale transformed
+// output. Using a record to skip plugin effects requires a reuse identity that
+// covers every relevant input and effect, not source text alone.
+//
+// @evidence contracts/common.md#principled-implementation A nil previous wrapper prevents reuse of old snapshot emit signatures/diagnostics and initializes applicable pending output under upstream emit controls; source-only prior state cannot establish plugin-effect equivalence.
+// @evidence contracts/common.md#clear-and-simple-design One upstream incremental-program construction owns full emit and build-info output, avoiding a separate record serializer or a partially reused emit path.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Fresh emission is grounded in absent plugin identity in the snapshot key, not a blanket retry masking stale output; no fake build-info or consumer-specific cache key is introduced.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the in-process build-info connection, fresh pending state, emit/cancellation/write limits and plugin-effect invalidation rather than unconditional output or incremental reuse.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This wrapper chooses snapshot reuse, while Program.Host and the upstream incremental emitter own native output-path and filesystem decisions.
+// @evidence contracts/performance.md#efficient-algorithms The fresh wrapper reuses the checked Program but builds snapshot file hashes, references and semantic metadata; eligible output then incurs emission and additional build-info table traversal/JSON serialization. File, reference, source/output-byte and diagnostic populations drive this work. Delegating the actual engine avoids a separate record implementation, not those traversals; prior snapshot skipping is unsafe without plugin-equivalent inputs/effects.
+// @evidence contracts/performance.md#reuse-equivalent-work The supplied checked Program is reused, while no previous incremental wrapper is admitted. Skipping effectful emission requires identity and invalidation covering all plugin/runtime/configuration/contributor dependencies and effects; quiet source text alone cannot authorize it.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The invocation acquires an incremental snapshot with file/reference/pending/diagnostic state plus temporary emission and build-info serialization storage. It retains the supplied Program while upstream work runs; returned results and WriteFile callback data may retain output or semantic references afterward. This adapter keeps no historical snapshot registry or independent running-task owner, and caller/host/upstream own result, callback and Program lifetimes on success, error or cancellation.
+func EmitFreshWithBuildInfo(ctx context.Context, program *Program, options EmitOptions) *EmitResult {
+  incrementalProgram := incremental.NewProgram(
+    program,
+    nil,
+    incremental.CreateHost(program.Host()),
+    time.Now,
+    false,
+  )
+  return incrementalProgram.Emit(ctx, options)
+}
+
+//go:linkname incrementalGetReferencedFiles github.com/microsoft/TypeScript/tsc/internal/execute/incremental.getReferencedFiles
+func incrementalGetReferencedFiles(program *innercompiler.Program, file *innerast.SourceFile) *collections.Set[tspath.PathKey]
+
+//go:linkname incrementalFileAffectsGlobalScope github.com/microsoft/TypeScript/tsc/internal/execute/incremental.fileAffectsGlobalScope
+func incrementalFileAffectsGlobalScope(file *innerast.SourceFile) bool
+
+// GetReferencedFilePaths adapts the upstream incremental reference set:
+// import/re-export and string module-augmentation symbols' declaration files,
+// path directives, resolved type directives and ambient-module declarations.
+// It is not a transitive symbol-reachability closure or proof that every path
+// is a loaded source. Extensionless path-directive adaptation below can also
+// differ from the raw upstream build-info entry.
+//
+// The returned keys are tspath.PathKey values (case-canonicalized on
+// case-insensitive filesystems); map them back to real file names through
+// Program.GetSourceFileByPath when the original spelling matters.
+// Extensionless path references are replaced with the source file Program
+// actually loaded because the upstream incremental helper retains their raw
+// directive path instead of the selected extension-bearing path.
+// Program and file must be nonnil and belong to the same loaded program.
+// Returned order follows the compiler's reference set; it is not sorted.
+//
+// @evidence contracts/common.md#principled-implementation Upstream's semantic reference set is combined with the same program's resolved path directives, replacing extensionless raw paths with loaded source identities and deduplicating canonical paths; project-reference redirects use the program's actual declaration-to-source mapping.
+// @evidence contracts/common.md#clear-and-simple-design The exported function owns reference-set adaptation while a private helper resolves resident and virtual declaration sources through one program context.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The extra project-reference lookup addresses supported unbuilt declaration outputs using compiler redirects and supported extensions, rather than guessing filenames or special-casing projects.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs identify reference categories, canonical spelling, extension replacement, same-program premises and unsorted output with descriptive text separate from tags.
+// @evidence contracts/portability.md#os-neutral-implementation Path identity uses the Program's own path keys and compiler path helpers, while project-reference redirects recover the loaded filename rather than inferring native case behavior from the OS.
+// @evidence contracts/performance.md#efficient-algorithms Adaptation uses expected linear map/set processing in upstream reference count plus path-directive count, with path-text hashing/canonicalization and a bounded supported-extension search per unresolved directive. Before that, upstream obtains a checker and visits import/augmentation symbols, their declarations and ambient modules; semantic lookup, declaration parent walks and host/project-reference queries are additional delegated work, not bounded by the returned path count alone.
+// @evidence contracts/performance.md#reuse-equivalent-work Loaded Program resolutions, sources and checker state are reused, while the reference set and adaptation maps are rebuilt per invocation. Upstream checker queries may populate semantic caches; this adapter coordinates no cross-Program cache or separate resolver producer.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream acquires a file checker with a deferred release callback and may retain semantic state under its Program/checker owner. Reference, replacement and deduplication sets are invocation-local; returned slice/string ownership transfers to the caller and may share existing path backing storage. The bridge keeps no historical result registry.
+func GetReferencedFilePaths(program *Program, file *innerast.SourceFile) []tspath.PathKey {
+  set := incrementalGetReferencedFiles(program, file)
+  if set == nil {
+    return nil
+  }
+  resolvedPathReferences := make(map[tspath.PathKey]tspath.PathKey, len(file.ReferencedFiles))
+  sourceDirectory := file.FileName().Directory()
+  for _, reference := range file.ReferencedFiles {
+    referencedFile := tspath.ToRootedFilePath(reference.FileName, sourceDirectory)
+    if redirect := program.GetParseFileRedirect(referencedFile); redirect != "" {
+      referencedFile = redirect
+    }
+    rawPath := program.PathKeyForFileName(referencedFile)
+    if resolved := getSourceFileFromReference(program, file, reference); resolved != nil {
+      resolvedPathReferences[rawPath] = resolved.PathKey()
+    }
+  }
+  out := make([]tspath.PathKey, 0, set.Len())
+  seen := collections.Set[tspath.PathKey]{}
+  for path := range set.Keys() {
+    if resolved := resolvedPathReferences[path]; resolved != "" {
+      path = resolved
+    }
+    if seen.Has(path) {
+      continue
+    }
+    seen.Add(path)
+    out = append(out, path)
+  }
+  return out
+}
+
+// getSourceFileFromReference extends TypeScript-Go's resident-file lookup with
+// the virtual declaration outputs its project-reference filesystem accepts.
+// The upstream helper cannot see an unbuilt output in Program.filesByPath, but
+// the project-reference mapper retains the output-to-source redirect that made
+// the reference valid while the Program was loaded.
+func getSourceFileFromReference(program *Program, file *innerast.SourceFile, reference *innerast.FileReference) *innerast.SourceFile {
+  if resolved := program.GetSourceFileFromReference(file, reference); resolved != nil {
+    return resolved
+  }
+  referencedFile := tspath.ToRootedFilePath(reference.FileName, file.FileName().Directory())
+  if referencedFile.HasExtension() {
+    return nil
+  }
+  supportedExtensions := innertsoptions.GetSupportedExtensions(program.Options(), nil)
+  supportedExtensions = innertsoptions.GetSupportedExtensionsWithJsonIfResolveJsonModule(program.Options(), supportedExtensions)
+  for _, extension := range supportedExtensions[0] {
+    outputPath := program.PathKeyForFileName(referencedFile.AppendSuffix(extension))
+    redirect := program.GetProjectReferenceFromOutputDts(outputPath)
+    if redirect == nil {
+      continue
+    }
+    if source := program.GetSourceFile(redirect.Source); source != nil {
+      return source
+    }
+  }
+  return nil
+}
+
+// FileAffectsGlobalScope reports the upstream incremental engine's global
+// impact classification, first ensuring the source file is bound. A global
+// augmentation is true; otherwise external/CommonJS modules and JSON are false.
+// A remaining script is true only when it has a statement other than a
+// string-literal-named module declaration. Empty or ambient-external-only
+// scripts are not automatically global-impact files.
+// file must be a nonnil compiler source file.
+//
+// @evidence contracts/common.md#principled-implementation The wrapper delegates the pinned incremental engine's global-scope predicate, preserving the same distinction used for program-wide semantic invalidation.
+// @evidence contracts/common.md#clear-and-simple-design One predicate exposes compiler-owned classification without an independent global-scope analysis.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No path, project name or expected invalidation result is special-cased; the foreign predicate remains unchanged.
+// @evidence contracts/common.md#meaningful-documentation Native prose states binding, augmentation/module/JSON/script distinctions, empty/ambient-only limits and the nonnil source-file premise without certifying every edit's runtime invalidation result.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Global-scope syntax classification has no native filesystem or process boundary.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream binding and global-impact classification own their algorithms: an unbound file can incur AST binding, then augmentation/statement scans short-circuit according to the classification. This direct bridge chooses no independent traversal or impact analysis.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream IsBound/BindOnce and its binder pool own binding reuse; this bridge coordinates no separate impact-result cache or cross-generation producer/invalidation policy.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Binding can acquire a pooled binder and populate source-owned symbols, flow and classification state; its defer returns and resets the binder while that bound AST state survives under the file owner. The bridge returns only a boolean and keeps no independent state registry or handle, but does not equate that with absence of delegated retention.
+func FileAffectsGlobalScope(file *innerast.SourceFile) bool {
+  return incrementalFileAffectsGlobalScope(file)
+}

package/targets/7.1/bridge/compiler/neutral.go

@@ -0,0 +1,256 @@
+package compiler
+
+import (
+  "context"
+  "errors"
+  "sync"
+
+  innerast "github.com/microsoft/TypeScript/tsc/internal/ast"
+  innercompiler "github.com/microsoft/TypeScript/tsc/internal/compiler"
+  "github.com/microsoft/TypeScript/tsc/internal/contentmapper"
+  innercore "github.com/microsoft/TypeScript/tsc/internal/core"
+  innerlocale "github.com/microsoft/TypeScript/tsc/internal/locale"
+  inneroutputpaths "github.com/microsoft/TypeScript/tsc/internal/outputpaths"
+  innertsoptions "github.com/microsoft/TypeScript/tsc/internal/tsoptions"
+  innertspath "github.com/microsoft/TypeScript/tsc/internal/tspath"
+  innervfs "github.com/microsoft/TypeScript/tsc/internal/vfs"
+)
+
+// Version-neutral compiler operations.
+//
+// The TypeScript 7.0 and 7.1 compilers construct hosts, update Programs and
+// report path identity through different signatures. Code that must compile on
+// both compiler targets calls these functions, which the 7.0 shim declares
+// with identical signatures. Here each makes the 7.1 call.
+
+// NewHost returns a compiler host over fs that finds the bundled library files
+// at defaultLibraryPath. TypeScript 7.0 hosts carry currentDirectory as the
+// Program's working directory; TypeScript 7.1 takes it from the parsed config,
+// so here it is unused.
+//
+// @evidence contracts/common.md#principled-implementation Calls NewCompilerHost with the filesystem and library path and no config cache, trace or content-mapper project; 7.1 hosts carry no working directory.
+// @evidence contracts/common.md#clear-and-simple-design One constructor call keeps the target difference inside the shim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No host behavior is reimplemented here.
+// @evidence contracts/common.md#meaningful-documentation Native prose states each target's use of currentDirectory.
+// @evidence contracts/portability.md#os-neutral-implementation The supplied FS owns every native operation the host later makes; construction performs none.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Construction assigns fields and chooses no algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call returns a fresh host; callers share one by holding it.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The host retains fs and the library path for the caller's lifetime and owns no handle.
+func NewHost(currentDirectory innertspath.RootedDirectoryPath, fs innervfs.FS, defaultLibraryPath innertspath.RootedDirectoryPath) innercompiler.CompilerHost {
+  return innercompiler.NewCompilerHost(fs, defaultLibraryPath, nil, nil, nil)
+}
+
+// ProjectHosts builds the compiler hosts of the Programs one parsed project
+// produces and owns what those hosts share. On TypeScript 7.1 that is the
+// project's content mappers: when the config declares `contentMappers` and the
+// command line passed `--runExternalCode`, every host transforms content-mapped
+// files through one mapper project, and Close stops the mapper processes. A nil
+// ProjectHosts builds plain hosts. TypeScript 7.0 has no content mappers.
+//
+// @evidence contracts/common.md#principled-implementation Mirrors tsc's own setup: a content-mapper host and its ProjectSpec project exist only under runExternalCode with configured mappers, and the project is handed to every compiler host.
+// @evidence contracts/common.md#clear-and-simple-design One value pairs host construction with the release of the mapper state the hosts share, so incremental hosts keep the project the first host used.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The compiler's own runExternalCode gate and mapper resolution decide whether mappers run; no ttsc authorization or mapping policy is added.
+// @evidence contracts/common.md#meaningful-documentation Native prose states when mappers run, the nil meaning and the 7.0 difference.
+// @evidence contracts/portability.md#os-neutral-implementation Mapper processes start through spawnContentMapper's os/exec boundary in each mapper package's directory; the supplied FS owns every file read.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The type stores two handles and chooses no algorithm.
+// @evidence contracts/performance.md#reuse-equivalent-work Every host built from one ProjectHosts shares one mapper project, so an incremental generation reuses the processes the first generation started.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The mapper project and host, and with them every spawned mapper process, live until Close; Close releases them once.
+type ProjectHosts struct {
+  mappers   contentmapper.Host
+  project   contentmapper.Project
+  closeOnce sync.Once
+  closeErr  error
+}
+
+// NewProjectHosts returns the hosts of Programs built from config. It starts
+// no process: mapper processes start when a host first reads a mapped file.
+//
+// @evidence contracts/common.md#principled-implementation Opens the content-mapper host and project exactly as tsc's NewContentMapperHost and getContentMapperProject do, from the config's resolved mappers and effective options.
+// @evidence contracts/common.md#clear-and-simple-design One gate returns either a nil value or a value holding the mapper project.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Mapper resolution and its diagnostics stay with the config parser; this function adds none.
+// @evidence contracts/common.md#meaningful-documentation Native prose states that construction starts no process.
+// @evidence contracts/portability.md#os-neutral-implementation Construction performs no native operation; mapper processes start later through spawnContentMapper.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Construction checks one option and one slice length.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call opens its own mapper state; callers share it by holding the value.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned value owns the mapper host and project until Close.
+func NewProjectHosts(config *innertsoptions.ParsedCommandLine) *ProjectHosts {
+  if config == nil || !config.CompilerOptions().RunExternalCode.IsTrue() || len(config.ContentMappers()) == 0 {
+    return nil
+  }
+  diagnosticLocale, _ := innerlocale.Parse(config.CompilerOptions().Locale)
+  mappers := contentmapper.NewHost(context.Background(), contentmapper.SpawnerFunc(spawnContentMapper), diagnosticLocale)
+  return &ProjectHosts{
+    mappers: mappers,
+    project: mappers.Project(contentmapper.ProjectSpec{
+      ConfigFileName:  config.ConfigName(),
+      Mappers:         config.ContentMappers(),
+      CompilerOptions: config.CompilerOptions(),
+    }),
+  }
+}
+
+// Host returns a compiler host over fs, like NewHost, that transforms
+// content-mapped files through this project's mappers.
+//
+// @evidence contracts/common.md#principled-implementation Calls NewCompilerHost with the shared mapper project, the argument tsc passes for the same project.
+// @evidence contracts/common.md#clear-and-simple-design A nil receiver reduces to NewHost, so callers need no separate plain-host branch.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Content-mapped file loading stays the compiler host's.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the relation to NewHost.
+// @evidence contracts/portability.md#os-neutral-implementation The supplied FS owns every native read the host makes.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Construction assigns fields.
+// @evidence contracts/performance.md#reuse-equivalent-work Every returned host shares one mapper project.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The host borrows the project; Close on the ProjectHosts releases it.
+func (h *ProjectHosts) Host(currentDirectory innertspath.RootedDirectoryPath, fs innervfs.FS, defaultLibraryPath innertspath.RootedDirectoryPath) innercompiler.CompilerHost {
+  if h == nil {
+    return NewHost(currentDirectory, fs, defaultLibraryPath)
+  }
+  return innercompiler.NewCompilerHost(fs, defaultLibraryPath, nil, nil, h.project)
+}
+
+// Close closes the mapper project and stops every mapper process. Later calls
+// return the first result.
+//
+// @evidence contracts/common.md#principled-implementation Closes the project before its host, the order tsc releases them in.
+// @evidence contracts/common.md#clear-and-simple-design sync.Once makes release idempotent for every owner that closes it.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Both close errors are returned rather than dropped.
+// @evidence contracts/common.md#meaningful-documentation Native prose states repeated-call behavior.
+// @evidence contracts/portability.md#os-neutral-implementation Stopping a mapper closes its pipes and kills its process through os/exec.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Release closes two handles.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Release coordinates no shared computation.
+// @evidence contracts/performance.md#bound-retention-and-release-resources After Close no mapper process of this project remains; hosts built from it can no longer transform mapped files.
+func (h *ProjectHosts) Close() error {
+  if h == nil {
+    return nil
+  }
+  h.closeOnce.Do(func() {
+    h.closeErr = errors.Join(h.project.Close(), h.mappers.Close())
+  })
+  return h.closeErr
+}
+
+// UpdateProgram returns a Program in which only the file keyed by changed was
+// edited, the changed file as host parsed it, and whether the old Program's
+// data was reused. A nil Program means the update could not be made.
+//
+// @evidence contracts/common.md#principled-implementation Calls Program.UpdateProgram with the Program's own checker pool and module resolver.
+// @evidence contracts/common.md#clear-and-simple-design One method call keeps the target difference inside the shim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Reuse decisions remain the compiler's.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the three results and the nil meaning.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The host owns any filesystem read; this call adds none.
+// @evidence contracts/performance.md#efficient-algorithms The compiler reparses only the changed file and reuses the rest when it can.
+// @evidence contracts/performance.md#reuse-equivalent-work The compiler decides reuse of the old Program's files and data.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The new Program may share data with the old one; the caller owns releasing the old Program's checkers.
+func UpdateProgram(program *innercompiler.Program, changed innertspath.PathKey, host innercompiler.CompilerHost) (*innercompiler.Program, *innerast.SourceFile, bool) {
+  return program.UpdateProgram(changed, host, nil, nil)
+}
+
+// ProgramCaseSensitivity reports the case policy the Program compares file
+// names with.
+//
+// @evidence contracts/common.md#principled-implementation Returns Program.CaseSensitivity.
+// @evidence contracts/common.md#clear-and-simple-design One method call keeps the target difference inside the shim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The policy is the Program's own, not probed again.
+// @evidence contracts/common.md#meaningful-documentation Native prose names what the policy governs.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The Program answers from its stored policy without a native call.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A stored value is returned.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The function coordinates no shared work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function retains nothing.
+func ProgramCaseSensitivity(program *innercompiler.Program) innertspath.CaseSensitivity {
+  return program.CaseSensitivity()
+}
+
+// ProgramPathKey returns the key the Program files fileName under, which is
+// the canonical form of its absolute path.
+//
+// @evidence contracts/common.md#principled-implementation Returns Program.PathKeyForFileName, the key the Program indexes its files by.
+// @evidence contracts/common.md#clear-and-simple-design One method call keeps the target difference inside the shim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No path canonicalization is reimplemented here.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the canonical-key meaning.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Key derivation manipulates path text only.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The compiler owns the canonicalization.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The function coordinates no shared work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function retains nothing beyond the returned key.
+func ProgramPathKey(program *innercompiler.Program, fileName innertspath.RootedFilePath) innertspath.PathKey {
+  return program.PathKeyForFileName(fileName)
+}
+
+// SourceFilesToEmit returns the program files a whole-program emit writes.
+//
+// @evidence contracts/common.md#principled-implementation Calls 7.1's GetSourceFilesToEmit with no target files and no forced declaration or JavaScript emit, the emitter's whole-program file set.
+// @evidence contracts/common.md#clear-and-simple-design One call per target keeps compiler signature differences out of every emit caller.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts File selection remains the compiler's.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the whole-program scope.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Selection reads Program state and performs no native operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The compiler owns the file scan.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The function coordinates no shared work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned slice is caller-owned.
+func SourceFilesToEmit(host innercompiler.SourceFileMayBeEmittedHost) []*innerast.SourceFile {
+  return GetSourceFilesToEmit(host, nil, false, false)
+}
+
+// OutputPathsFor returns the emitter's output paths for one source file
+// without forcing declaration paths.
+//
+// @evidence contracts/common.md#principled-implementation Calls 7.1's GetOutputPathsFor with an empty ForceEmitPaths, the paths the emitter writes.
+// @evidence contracts/common.md#clear-and-simple-design One call per target keeps compiler signature differences out of every emit caller.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Path derivation remains the compiler's.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the unforced mode.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Path derivation manipulates path text only.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The compiler owns the derivation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The function coordinates no shared work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned paths are caller-owned.
+func OutputPathsFor(source *innerast.SourceFile, options *innercore.CompilerOptions, host inneroutputpaths.OutputPathsHost) *inneroutputpaths.OutputPaths {
+  return GetOutputPathsFor(source, options, host, ForceEmitPaths{})
+}
+
+// TargetedEmitOptions returns EmitOptions that emit target alone through
+// writeFile, or the whole program when target is nil.
+//
+// @evidence contracts/common.md#principled-implementation Sets 7.1's TargetSourceFiles list to the single target, or leaves it nil for a whole-program emit.
+// @evidence contracts/common.md#clear-and-simple-design One constructor per target keeps EmitOptions field differences out of every emit caller.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Emit scope remains the compiler's interpretation of the field.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the nil meaning.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Construction performs no native operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Construction assigns two fields.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The function coordinates no shared work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned value is caller-owned.
+func TargetedEmitOptions(target *innerast.SourceFile, writeFile innercompiler.WriteFile) innercompiler.EmitOptions {
+  var targets []*innerast.SourceFile
+  if target != nil {
+    targets = []*innerast.SourceFile{target}
+  }
+  return innercompiler.EmitOptions{TargetSourceFiles: targets, WriteFile: writeFile}
+}
+
+// EmitsWholeProgram reports whether options name no target file.
+//
+// @evidence contracts/common.md#principled-implementation Reads 7.1's TargetSourceFiles list.
+// @evidence contracts/common.md#clear-and-simple-design One predicate per target keeps EmitOptions field differences out of every emit caller.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The predicate reads the field the compiler reads.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the predicate.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The predicate performs no native operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The predicate reads one field.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The function coordinates no shared work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The function retains nothing.
+func EmitsWholeProgram(options innercompiler.EmitOptions) bool {
+  return options.TargetSourceFiles == nil
+}
+
+// NewProgramOptions returns the options of a Program over config built through
+// host. useSourceOfProjectReference reads a referenced project's sources rather
+// than its declaration outputs. Every other option keeps the compiler default.
+//
+// @evidence contracts/common.md#principled-implementation Fills 7.1's ProgramConfig and ProgramHosts groups.
+// @evidence contracts/common.md#clear-and-simple-design One constructor per target keeps ProgramOptions' layout difference out of every Program caller.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The returned options leave every other field at the compiler's default.
+// @evidence contracts/common.md#meaningful-documentation Native prose names the three fields set and the defaults.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Construction performs no native operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Construction assigns three fields.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The function coordinates no shared work.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned options reference the caller's config and host without copying them.
+func NewProgramOptions(config *innertsoptions.ParsedCommandLine, host innercompiler.CompilerHost, useSourceOfProjectReference bool) innercompiler.ProgramOptions {
+  return innercompiler.ProgramOptions{
+    ProgramConfig: innercompiler.ProgramConfig{Config: config, UseSourceOfProjectReference: useSourceOfProjectReference},
+    ProgramHosts:  innercompiler.ProgramHosts{Host: host},
+  }
+}