ttsc 0.30.4 → 0.31.0

package/driver/resolution_candidates.go

@@ -9,42 +9,82 @@ import (
   shimtspath "github.com/microsoft/typescript-go/shim/tspath"
 )
 
-// ProgramResolutionInput is one exact lexical filesystem input consulted by
-// TypeScript-Go while resolving a resident Program.
+// ProgramResolutionInput is one reported lexical filesystem input from
+// TypeScript-Go resolution replay for a resident Program. The observer retains
+// the first cleaned spelling per compiler-normalized case key, not every raw
+// spelling passed to filesystem methods.
+//
+// @evidence contracts/common.md#principled-implementation Enumeration and identity-only flags distinguish directory membership from alias identity whose bytes are already owned by a graph target.
+// @evidence contracts/common.md#clear-and-simple-design One lexical path carries the two independent invalidation qualifications.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A selected alias is not dropped merely because another spelling owns its content.
+// @evidence contracts/common.md#meaningful-documentation Native member prose explains membership and identity-only invalidation following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Path carries the observer's first native cleaned spelling per compiler-normalized case key, distinct from successful realpath identity. Flags qualify directory enumeration and selected-target alias responsibility; they do not establish OS-default case policy or preserve every raw alias spelling.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Resolution replay owns observation collection; this type describes one input.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This data value coordinates no shared work.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The input value owns no resource or resident cache.
 type ProgramResolutionInput struct {
   // DirectoryEntries is true when the compiler enumerated this directory, so
   // membership changes as well as kind and identity must invalidate it.
   DirectoryEntries bool
+
   // IdentityOnly is true only for a selected lexical alias whose contents are
   // already owned by the resolved graph target. A link retarget must still
   // invalidate it, while an edit to the selected bytes is not counted twice.
   IdentityOnly bool
-  Path         string
+
+  // Path is the first cleaned spelling retained for its compiler observation key.
+  Path string
 }
 
-// ProgramResolutionObservation is the deterministic result of replaying every
-// resident module and type-reference resolution through TypeScript-Go itself.
+// ProgramResolutionObservation reports resident module/type-reference replay
+// and automatic type discovery through TypeScript-Go. Ordering/compaction are
+// deterministic for the supplied tasks and observed inputs, not a promise that
+// concurrent filesystem changes produce the same observations.
+//
+// @evidence contracts/common.md#principled-implementation Source candidates, universal inputs, and replay mismatches remain distinct so automatic type discovery can invalidate every source correctly.
+// @evidence contracts/common.md#clear-and-simple-design One result exposes envelope and flat-host views of the same replay transaction.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Replay mismatches remain proof failures rather than a presumed matching resolver result.
+// @evidence contracts/common.md#meaningful-documentation Native field prose explains candidate, universal, flat, and failure scopes following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The observation retains exact native resolver inputs, with envelope serialization performed by the shared output-key owner.
+// @evidenceExclude contracts/performance.md#efficient-algorithms ObserveProgramResolutions owns replay and sorting; the type is its result.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This result supplies proof to consumers without coordinating artifact reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The result is caller-owned and acquires no resource or resident cache.
 type ProgramResolutionObservation struct {
-  // Candidates maps each source to every exact resolver input other than its
-  // identically spelled selected graph target.
+  // Candidates maps each source to reported resolver spellings. A selected
+  // resident target is omitted when compiler-normalized equality already owns
+  // it; a separately observed physical alias remains an identity input.
   Candidates map[string][]string
+
   // Failures marks source files whose replay no longer matched the resident
   // resolution. A universal failure is expanded to every graph source later.
   Failures map[string]string
+
   // Inputs is the flat form used by resident non-envelope hosts.
   Inputs []ProgramResolutionInput
+
   // Universal contains automatic type discovery and resolution inputs whose
   // state can affect every source file.
-  Universal        []string
+  Universal []string
+
   universalFailure bool
 }
 
-// ObserveProgramResolutions replays the pinned TypeScript-Go resolver over a
-// fresh observation transaction per source resolution set. This preserves the
-// compiler's exact ordering and complete semantics without maintaining a
-// second resolver in ttsc. Replay observations are merged into the original
-// compiler transaction, so a state change between construction and replay
-// becomes a proof failure.
+// ObserveProgramResolutions replays cached module/type-reference tasks and
+// automatic type discovery through the pinned TypeScript-Go compiler, with a
+// fresh observation transaction per resolution-owner group. Triple-slash path
+// references separately use ttsc's candidate procedure with compiler-supported
+// extensions and project-reference redirects. Replay observations merge into
+// the original compiler transaction; observed contradictions or mismatched
+// cached resolutions become proof failures, not an atomic filesystem snapshot.
+//
+// @evidence contracts/common.md#principled-implementation The pinned compiler replays module/type discovery semantics, and merged observations make intervening filesystem changes explicit proof failures.
+// @evidence contracts/common.md#clear-and-simple-design Deterministic task grouping separates source-owned and universal observations; shared helpers normalize and compact output.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Cached module/type-reference results are compared by native compiler replay; path references use explicit supported-extension/redirect predicates rather than claiming to be that same module resolver. Successful targets outside the resident graph remain inputs because only loaded source targets qualify for graph-content ownership.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains transaction scope, compiler ownership, and change detection following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler path/case operations and the actual FS case capability govern alias equality, supported extensions, and envelope keys.
+// @evidence contracts/performance.md#efficient-algorithms Task extraction/sorting and adjacent-owner grouping avoid one replay per individual task. Native module/type discovery, path-reference candidate probes and predicate bytes remain delegated costs; each observed path scans its group's selected targets for canonical/physical alias comparison before final map/set compaction and path sorting. Costs include task/reference/candidate/selected-target populations, path comparisons and filesystem reads/enumeration; no work or byte ceiling is supplied.
+// @evidence contracts/performance.md#reuse-equivalent-work One observation transaction serves each resolution-owner group; selected graph targets retain content ownership while alias identity is kept without duplicating content responsibility.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Temporary tasks, per-group observers and final input maps/slices grow with resolutions, native predicates, names and path bytes. Replay observations merge into the caller-owned current Program observer and the output transfers to its caller. No previous-generation observation cache is owned here, but neither merged/current data nor returned bytes have a population cap or disposal policy imposed by this function.
 func ObserveProgramResolutions(prog *Program, cwd string) ProgramResolutionObservation {
   output := ProgramResolutionObservation{
     Candidates: map[string][]string{},
@@ -219,6 +259,15 @@ func supportedFileExtension(file string, supported [][]string) bool {
 
 // ApplyUniversalResolutionFailure marks every source because automatic type
 // discovery contributes to one global Program rather than to one importer.
+//
+// @evidence contracts/common.md#principled-implementation Universal type-discovery failure qualifies every realized graph source rather than only one importer.
+// @evidence contracts/common.md#clear-and-simple-design One failure guard precedes a single source-map iteration.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Unchanged source text cannot hide a changed automatic type environment.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the global invalidation reason following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This method marks existing envelope keys and performs no native operation.
+// @evidence contracts/performance.md#efficient-algorithms A false universal-failure guard visits no sources. Otherwise one pass assigns each realized source's reason, including map hashing/comparison work for its key text; no target lists or transitive graph closures are traversed.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The method propagates an existing failure and coordinates no shared computation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It modifies the caller-owned observation without acquiring an independent cache or resource.
 func (observation ProgramResolutionObservation) ApplyUniversalResolutionFailure(sources map[string][]string) {
   if !observation.universalFailure {
     return

package/driver/resolution_candidates_test.go

@@ -8,7 +8,18 @@ import (
   "testing"
 )
 
+// TestTransformGraphReplaysCompilerResolutionSemantics loads authored native
+// projects and checks selected resolver candidates, type-root membership,
+// project-reference edges and observations, and semantic config selection.
+// Required candidate membership is checked rather than an exact candidate set;
+// the same maintained compiler supplies the Program and resolution replay.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual LoadProgram and NewTransformGraph expose the asserted package/import/suffix/reference candidate paths and type-root listing. Additional fixtures check JSON-reference admission, a noResolve target outside the Program, unbuilt project-reference resident versus nonresident edges, and explicit versus absent or relative semantic config selection.
+// @evidence contracts/testing.md#independent-expectations Required candidate paths, project-reference edge presence/absence, and selected config filenames are authored literals. The explicit wildcard type root contains exactly fixture-types and no files; independent native EvalSymlinks supplies its expected directory identity. Candidates are not checked for exact equality, and the uppercase JSON expectation uses the Program's filesystem case policy; this does not independently certify that policy or the compiler's full resolver semantics. Wildcard type enumeration is not claimed for an omitted types option.
+// @evidence contracts/testing.md#distinguishing-cases resolveJsonModule false/true and conditional uppercase admission contrast; noResolve retains a successful target as a candidate. Project-reference source presence and output absence differ from realized edge membership. Explicit absolute semantic config, an unmarked wrapper despite ambient metadata, and a rejected relative semantic path exercise separate selection branches.
+// @evidence contracts/testing.md#execution-ownership This driver Go unit writes and cleans its own temporary projects, constructs maintained native compiler Programs in-process, and calls the owning graph operation. Each returned Program is closed; a restored empty linked-plugin manifest excludes ambient hooks, and no installed consumer or external compiler command is used. It does not substitute a literal-input-only aggregation test for this native compiler connection.
 func TestTransformGraphReplaysCompilerResolutionSemantics(t *testing.T) {
+  t.Setenv(LinkedPluginsEnv, "")
   root := t.TempDir()
   files := map[string]string{
     "package.json": `{
@@ -92,6 +103,23 @@ export const value: Folder = { value: internal + self };
   if entries == nil || !slices.Contains(entries.Directories, "fixture-types") {
     t.Fatalf("automatic type-root listing = %#v", entries)
   }
+  if !slices.Equal(entries.Directories, []string{"fixture-types"}) || len(entries.Files) != 0 {
+    t.Errorf("wildcard type-root exact accessible population = %#v", entries)
+  }
+  typeObservation := graph.InputObservations[typeRoot]
+  if typeObservation.DirectoryExists == nil || !*typeObservation.DirectoryExists {
+    t.Errorf("wildcard type-root directory predicate = %#v", typeObservation.DirectoryExists)
+  }
+  physicalTypeRoot, err := filepath.EvalSymlinks(filepath.Join(root, "node_modules", "@types"))
+  if err != nil {
+    t.Fatal(err)
+  }
+  if typeObservation.Realpath == nil || !typeObservation.Realpath.OK || filepath.Clean(typeObservation.Realpath.Path) != filepath.Clean(physicalTypeRoot) {
+    t.Errorf("wildcard type-root observed identity = %#v, want %q", typeObservation.Realpath, physicalTypeRoot)
+  }
+  if projected := graph.InputRealpaths[typeRoot]; projected == nil || filepath.Clean(*projected) != filepath.Clean(physicalTypeRoot) {
+    t.Errorf("wildcard type-root projected identity = %#v, want %q", projected, physicalTypeRoot)
+  }
   if len(graph.InputProofFailures) != 0 {
     t.Fatalf("stable exact replay reported failures: %#v", graph.InputProofFailures)
   }