ttsc 0.30.4 → 0.31.1

package/driver/transform_source_map.go

@@ -0,0 +1,388 @@
+package driver
+
+import (
+  "encoding/base64"
+  "encoding/json"
+  "fmt"
+  "path"
+  "strings"
+  "unicode/utf16"
+
+  "github.com/microsoft/typescript-go/shim/ast"
+  shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+)
+
+// AuthoredSourceMap removes the configured preamble from the supplied parsed
+// source text and corrects a map printed from that source's current Program.
+// file must be non-nil and belong to the matching program/preamble generation.
+// The result is parsed text without that region, not original disk-encoding or
+// independent file-consumption provenance.
+//
+// A source preamble is inserted into the text TypeScript-Go parses, so every
+// position a printer records for a preamble-bearing file lies in that text
+// rather than in the file its author wrote, and `sourcesContent` carries the
+// preamble too. Each such source is remapped exactly: a position before the
+// preamble is kept, one inside it is dropped, and one after it moves back by the
+// preamble's extent, on its own line or across lines. This covers a BOM, a
+// hashbang, and a preamble that does not end a line. Present non-null
+// `sourcesContent` entries for corrected sources become their region-stripped
+// text. Without a preamble both values pass through without map validation.
+// Required JSON fields are decoded; segment-shape checks run only when a source
+// region is found. This is not a complete source-map validator. A false result
+// requires discarding the map rather than publishing it uncorrected.
+//
+// @evidence contracts/common.md#principled-implementation Recognized configured regions map parsed coordinates to region-stripped text using line and UTF-16 columns. Required-field or applicable segment-shape failure returns false; unresolved/non-region sources retain their coordinates and absence of a region does not certify complete map validity.
+// @evidence contracts/common.md#clear-and-simple-design Region discovery, position remapping, and sourcesContent restoration have separate helpers under one correction operation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts BOM, hashbang, and same-line insertion use actual source extents rather than a fixed line-offset patch.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs define before/inside/after positions, authored content, and failure policy following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler filenames and source-map URLs use slash-based path operations; resident source lookup delegates native canonicalization to the compiler.
+// @evidence contracts/performance.md#efficient-algorithms JSON and map serialization process map bytes; each sources entry resolves its filename and region, so duplicate entries may repeat lookup/region work. Region detection scans filename/prefix/preamble text and may copy authored content; any pending SourceFile hooks add their own work. Segment decoding/remapping/encoding and optional content arrays scale with map/source bytes and temporary storage.
+// @evidence contracts/performance.md#reuse-equivalent-work Each source's region is reused for all mapped segments rather than rediscovering the preamble for every position.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Region metadata is local to the correction and no external resource or resident cache is retained.
+func (p *Program) AuthoredSourceMap(file *ast.SourceFile, sourceMap string) (authored string, corrected string, ok bool) {
+  if p == nil || p.SourcePreamble == "" {
+    return file.Text(), sourceMap, true
+  }
+  authored = file.Text()
+  if start, length, found := sourcePreambleRegion(file.FileName(), authored, p.SourcePreamble); found {
+    authored = authored[:start] + authored[start+length:]
+  }
+  directory := path.Dir(file.FileName())
+  corrected, ok = correctAuthoredSourceMap(sourceMap, func(source string) *authoredRegion {
+    name := sourceMapFileName(source, directory)
+    target := file
+    if name != file.FileName() {
+      target = p.SourceFile(name)
+    }
+    if target == nil {
+      return nil
+    }
+    return newAuthoredRegion(target.FileName(), target.Text(), p.SourcePreamble)
+  })
+  return authored, corrected, ok
+}
+
+// NewSourceMapCorrector returns a generation-owned emitted-file correction
+// operation. It corrects external JS/declaration maps and inline map trailers
+// using the exact injected region of each original compiler source. Output
+// paths and sourceRoot/mapRoot follow the native emitter's source directory.
+//
+// Create it once per emit and discard it when that emit ends. Apply each map
+// once. Unknown output-directory association, required decoding failures and
+// applicable segment-shape failures return errors. This is not a complete map
+// validator: without a discovered region mapping validation is skipped, and
+// non-null sourcesContent restoration follows the captured InlineSources policy.
+// The compiler-selected build-information artifact passes through regardless
+// of its configured extension. Non-map outputs, programs without a source
+// preamble and programs with no enabled map option pass through unchanged
+// without map validation. Inline maps
+// use the last literal trailer marker, without parsing JavaScript comment syntax.
+// Calls must be serialized, and the captured compiler generation must remain
+// unchanged until that emit finishes.
+//
+// @evidence contracts/common.md#principled-implementation Recognized original compiler source regions qualify native emitted coordinates for the captured generation. Exact compiler-selected build-information identity excludes metadata before map-carrier classification. Unknown output association and required decoding or applicable segment-shape failure return errors; unresolved/non-region sources are not independently validated by this corrector.
+// @evidence contracts/common.md#clear-and-simple-design One output-directory index and shared exact map correction serve external and inline artifacts without another line-offset implementation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler output paths and SourceMapDirectory provide lookup anchors, and recognized byte regions replace fixed line-offset guesses. No full map-validation claim is inferred from a successful passthrough or unresolved source.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs specify generation ownership, supported map carriers, directory policy, single application, and error behavior following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Compiler path/case operations distinguish native output identity from raw source-map file URLs; published sourceRoot is not mistaken for the emitter's filesystem base.
+// @evidence contracts/performance.md#efficient-algorithms Construction indexes reached native emitted sources and their JS/declaration paths, including delegated output/directory and path-canonicalization costs. Each resolved source object's region is computed once; artifact handling scans filenames/inline text/base64/map JSON and segments, with source-prefix/UTF-16 work and optional content copies. Index, region, mapping/content arrays and output bytes scale with those populations and texts.
+// @evidence contracts/performance.md#reuse-equivalent-work Every artifact in one emit shares the output index and exact region cache for the same captured compiler generation and preamble.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The closure keeps its captured native program/options, output index and lazy source-object region cache reachable. Source count, paths and optional authored content have no configured byte/population cap; the caller must discard the closure when its serialized emit ends, and other aliases can retain captured values afterward. No process-global cache or new checker lease is acquired.
+func (p *Program) NewSourceMapCorrector() func(fileName, text string) (string, error) {
+  if p == nil || p.TSProgram == nil || p.SourcePreamble == "" {
+    return func(_ string, text string) (string, error) { return text, nil }
+  }
+  program, preamble := p.TSProgram, p.SourcePreamble
+  host := &pluginEmitHost{program: program}
+  options := program.Options()
+  if !options.SourceMap.IsTrue() && !options.InlineSourceMap.IsTrue() && !options.GetAreDeclarationMapsEnabled() {
+    return func(_ string, text string) (string, error) { return text, nil }
+  }
+  directories := map[shimtspath.Path]string{}
+  outputKey := func(name string) shimtspath.Path {
+    return shimtspath.ToPath(name, program.GetCurrentDirectory(), program.UseCaseSensitiveFileNames())
+  }
+  register := func(output, mapOutput string, source *ast.SourceFile) {
+    if output == "" {
+      return
+    }
+    directory := shimcompiler.SourceMapDirectory(options, host, output, source)
+    directories[outputKey(output)] = directory
+    if mapOutput != "" {
+      directories[outputKey(mapOutput)] = directory
+    }
+  }
+  for _, source := range shimcompiler.GetSourceFilesToEmit(host, nil, false) {
+    outputs := shimcompiler.GetOutputPathsFor(source, options, host, false)
+    register(outputs.JsFilePath(), outputs.SourceMapFilePath(), source)
+    register(outputs.DeclarationFilePath(), outputs.DeclarationMapPath(), source)
+  }
+  regions := map[*ast.SourceFile]*authoredRegion{}
+  resolve := func(source, directory string) *authoredRegion {
+    target := program.GetSourceFile(sourceMapFileName(source, directory))
+    if target == nil {
+      return nil
+    }
+    region, found := regions[target]
+    if !found {
+      region = newAuthoredRegionWithText(target.FileName(), target.Text(), preamble, options.InlineSources.IsTrue())
+      regions[target] = region
+    }
+    return region
+  }
+  return func(fileName, text string) (string, error) {
+    if p.isBuildInfoOutput(fileName) {
+      return text, nil
+    }
+    lower := strings.ToLower(fileName)
+    external := strings.HasSuffix(lower, ".map")
+    if !external && !isInlineSourceMapCarrier(lower) {
+      return text, nil
+    }
+    directory, known := directories[outputKey(fileName)]
+    if !known {
+      return "", fmt.Errorf("driver: source map output has no compiler source directory: %s", fileName)
+    }
+    mapText := text
+    start, end := 0, 0
+    if !external {
+      marker := strings.LastIndex(text, inlineSourceMapMarker)
+      if marker < 0 {
+        return text, nil
+      }
+      start = marker + len(inlineSourceMapMarker)
+      end = start
+      for end < len(text) && text[end] != '\n' && text[end] != '\r' {
+        end++
+      }
+      raw, err := base64.StdEncoding.DecodeString(strings.TrimRight(text[start:end], " \t"))
+      if err != nil {
+        return "", fmt.Errorf("driver: invalid inline source map in %s: %w", fileName, err)
+      }
+      mapText = string(raw)
+    }
+    corrected, valid := correctAuthoredSourceMap(mapText, func(source string) *authoredRegion { return resolve(source, directory) })
+    if !valid {
+      return "", fmt.Errorf("driver: invalid source map in %s", fileName)
+    }
+    if external {
+      return corrected, nil
+    }
+    return text[:start] + base64.StdEncoding.EncodeToString([]byte(corrected)) + text[end:], nil
+  }
+}
+
+// sourceMapFileName reverses the pinned generator's raw file-URL spelling.
+// GetRelativePathToDirectoryOrUrl does not percent-encode source names, so a
+// literal '%' remains filename data and must not undergo URL unescaping.
+func sourceMapFileName(source, directory string) string {
+  name := shimtspath.GetNormalizedAbsolutePath(source, directory)
+  if strings.HasPrefix(name, "file:///") {
+    drive := strings.TrimPrefix(name, "file:///")
+    if len(drive) >= 3 && drive[1] == ':' && drive[2] == '/' {
+      return drive
+    }
+  }
+  return strings.TrimPrefix(name, "file://")
+}
+
+// correctAuthoredSourceMap shares exact region removal between syntactic
+// printer maps and native emitted maps while each caller owns source lookup.
+func correctAuthoredSourceMap(sourceMap string, resolve func(string) *authoredRegion) (string, bool) {
+  var doc map[string]json.RawMessage
+  if json.Unmarshal([]byte(sourceMap), &doc) != nil {
+    return "", false
+  }
+  var sources []string
+  var mappings string
+  if json.Unmarshal(doc["sources"], &sources) != nil || json.Unmarshal(doc["mappings"], &mappings) != nil {
+    return "", false
+  }
+  regions := make([]*authoredRegion, len(sources))
+  anyRegion := false
+  for index, source := range sources {
+    if region := resolve(source); region != nil {
+      regions[index] = region
+      anyRegion = true
+    }
+  }
+  if !anyRegion {
+    return sourceMap, true
+  }
+  remapped, valid := remapSourcePositions(mappings, func(source, line, column int) (int, int, bool) {
+    if source < 0 || source >= len(regions) || regions[source] == nil {
+      return line, column, true
+    }
+    return regions[source].authoredPosition(line, column)
+  })
+  if !valid {
+    return "", false
+  }
+  encoded, err := marshalSourceMapJSON(remapped)
+  if err != nil {
+    return "", false
+  }
+  doc["mappings"] = encoded
+  if raw, present := doc["sourcesContent"]; present {
+    var contents []*string
+    if json.Unmarshal(raw, &contents) != nil {
+      return "", false
+    }
+    for index, region := range regions {
+      if region != nil && index < len(contents) && contents[index] != nil {
+        text := region.text
+        contents[index] = &text
+      }
+    }
+    if doc["sourcesContent"], err = marshalSourceMapJSON(contents); err != nil {
+      return "", false
+    }
+  }
+  out, err := marshalSourceMapJSON(doc)
+  if err != nil {
+    return "", false
+  }
+  return string(out), true
+}
+
+// authoredRegion is where a source preamble sits in one parsed file, in the
+// line and UTF-16 column coordinates a source map records, and that file's
+// authored text.
+type authoredRegion struct {
+  // startLine and startColumn locate the preamble's first character.
+  startLine, startColumn int
+
+  // endLine and endColumn locate the first character after it.
+  endLine, endColumn int
+
+  // text is the file without the preamble.
+  text string
+}
+
+// newAuthoredRegion locates preamble in the parsed text of fileName, or
+// returns nil when the preamble was never injected into it.
+func newAuthoredRegion(fileName, text, preamble string) *authoredRegion {
+  return newAuthoredRegionWithText(fileName, text, preamble, true)
+}
+
+// newAuthoredRegionWithText avoids copying entire authored source text when a
+// native map does not embed sourcesContent and only coordinates are needed.
+func newAuthoredRegionWithText(fileName, text, preamble string, includeText bool) *authoredRegion {
+  start, length, found := sourcePreambleRegion(fileName, text, preamble)
+  if !found {
+    return nil
+  }
+  startLine, startColumn := sourceMapPosition(text[:start])
+  preambleLines, lastColumn := sourceMapPosition(text[start : start+length])
+  endColumn := lastColumn
+  if preambleLines == 0 {
+    endColumn += startColumn
+  }
+  region := &authoredRegion{
+    startLine:   startLine,
+    startColumn: startColumn,
+    endLine:     startLine + preambleLines,
+    endColumn:   endColumn,
+  }
+  if includeText {
+    region.text = text[:start] + text[start+length:]
+  }
+  return region
+}
+
+// authoredPosition maps a parsed-text position to the authored text. ok is false
+// for a position inside the preamble, which the author never wrote.
+func (r *authoredRegion) authoredPosition(line, column int) (int, int, bool) {
+  if line < r.startLine || line == r.startLine && column < r.startColumn {
+    return line, column, true
+  }
+  if line < r.endLine || line == r.endLine && column < r.endColumn {
+    return 0, 0, false
+  }
+  if line == r.endLine {
+    return r.startLine, r.startColumn + column - r.endColumn, true
+  }
+  return line - (r.endLine - r.startLine), column, true
+}
+
+// sourceMapPosition returns the line and UTF-16 column reached at the end of
+// text, counting line terminators the way ECMAScript does.
+func sourceMapPosition(text string) (int, int) {
+  line, lineStart := 0, 0
+  for index := 0; index < len(text); {
+    switch {
+    case text[index] == '\r' && index+1 < len(text) && text[index+1] == '\n':
+      index += 2
+    case text[index] == '\r' || text[index] == '\n':
+      index++
+    case strings.HasPrefix(text[index:], "
") || strings.HasPrefix(text[index:], "
"):
+      index += len("
")
+    default:
+      index++
+      continue
+    }
+    line++
+    lineStart = index
+  }
+  return line, len(utf16.Encode([]rune(text[lineStart:])))
+}
+
+// remapSourcePositions rewrites every source position of a `mappings` string
+// through remap, dropping a segment remap rejects. valid is false when the
+// string cannot be decoded.
+func remapSourcePositions(mappings string, remap func(source, line, column int) (int, int, bool)) (string, bool) {
+  var source, sourceLine, sourceColumn, name int
+  var outSource, outSourceLine, outSourceColumn, outName int
+  lines := strings.Split(mappings, ";")
+  for lineIndex, line := range lines {
+    if line == "" {
+      continue
+    }
+    var column, outColumn int
+    segments := strings.Split(line, ",")
+    kept := make([]string, 0, len(segments))
+    for _, segment := range segments {
+      if segment == "" {
+        continue
+      }
+      fields := decodeVLQ(segment)
+      if len(fields) != 1 && len(fields) != 4 && len(fields) != 5 {
+        return "", false
+      }
+      column += fields[0]
+      if len(fields) == 1 {
+        kept = append(kept, encodeVLQ([]int{column - outColumn}))
+        outColumn = column
+        continue
+      }
+      source += fields[1]
+      sourceLine += fields[2]
+      sourceColumn += fields[3]
+      if len(fields) == 5 {
+        name += fields[4]
+      }
+      mappedLine, mappedColumn, keep := remap(source, sourceLine, sourceColumn)
+      if !keep {
+        continue
+      }
+      out := []int{
+        column - outColumn,
+        source - outSource,
+        mappedLine - outSourceLine,
+        mappedColumn - outSourceColumn,
+      }
+      if len(fields) == 5 {
+        out = append(out, name-outName)
+        outName = name
+      }
+      kept = append(kept, encodeVLQ(out))
+      outColumn = column
+      outSource = source
+      outSourceLine = mappedLine
+      outSourceColumn = mappedColumn
+    }
+    lines[lineIndex] = strings.Join(kept, ",")
+  }
+  return strings.Join(lines, ";"), true
+}

package/driver/windowsjunction/create_preserves_existing_directory_windows_test.go

@@ -0,0 +1,48 @@
+//go:build windows
+
+package windowsjunction
+
+import (
+  "os"
+  "path/filepath"
+  "testing"
+)
+
+// TestCreatePreservesExistingDirectory verifies an occupied link is rejected safely.
+//
+// An existing directory belongs to its caller. Junction creation must report
+// failure without replacing that directory or mutating the intended target.
+//
+//  1. Write distinct sentinel values in the occupied link and target directories.
+//  2. Attempt junction creation at the occupied link and require an error.
+//  3. Read both sentinels and require their original values.
+//
+// @evidence contracts/testing.md#behavioral-verification Create returns an error for an occupied link and leaves both caller-owned directories' sentinel bytes intact.
+// @evidence contracts/testing.md#independent-expectations Independently authored occupied and target bytes establish the preservation contract; a failed junction operation cannot replace caller-owned data.
+// @evidence contracts/testing.md#distinguishing-cases This negative case owns an already-existing link location and checks both the rejected destination and untouched target; the metacharacter case owns successful creation.
+// @evidence contracts/testing.md#execution-ownership Go test discovers this Windows Test entry and directly invokes the owning filesystem operation with its necessary mklink builtin, without an installed consumer, native build or product host.
+func TestCreatePreservesExistingDirectory(t *testing.T) {
+  root := t.TempDir()
+  link := filepath.Join(root, "occupied")
+  target := filepath.Join(root, "target")
+  for directory, content := range map[string]string{link: "occupied", target: "target"} {
+    if err := os.Mkdir(directory, 0o755); err != nil {
+      t.Fatal(err)
+    }
+    if err := os.WriteFile(filepath.Join(directory, "sentinel.txt"), []byte(content), 0o644); err != nil {
+      t.Fatal(err)
+    }
+  }
+  if err := Create(link, target); err == nil {
+    t.Fatal("Create succeeded at an occupied link")
+  }
+  for directory, want := range map[string]string{link: "occupied", target: "target"} {
+    got, err := os.ReadFile(filepath.Join(directory, "sentinel.txt"))
+    if err != nil {
+      t.Fatal(err)
+    }
+    if string(got) != want {
+      t.Fatalf("%s sentinel = %q, want %q", directory, got, want)
+    }
+  }
+}

package/driver/windowsjunction/create_treats_paths_as_data_windows_test.go

@@ -0,0 +1,55 @@
+//go:build windows
+
+package windowsjunction
+
+import (
+  "os"
+  "path/filepath"
+  "strings"
+  "testing"
+)
+
+// TestCreateTreatsPathsAsData verifies junction paths retain shell metacharacters.
+//
+// Delayed environment expansion must preserve literal percent expressions and
+// command metacharacters in both the target and the junction name.
+//
+//  1. Create a target containing an independently authored sentinel.
+//  2. Create and read a junction with ampersand, caret, exclamation, percent and parentheses.
+//  3. Assert exact sentinel content and absence of the environment-expanded link.
+//
+// @evidence contracts/testing.md#behavioral-verification Create makes a real junction whose sentinel reads safe through the literal metacharacter path; a shell-expanded alternate link must remain absent.
+// @evidence contracts/testing.md#independent-expectations The literal path strings and authored safe bytes establish the expected filesystem effect independently of Create's command composition.
+// @evidence contracts/testing.md#distinguishing-cases This case exercises metacharacters in both paths and contrasts the literal percent expression with its environment-expanded alternate; the existing-link case owns failure preservation.
+// @evidence contracts/testing.md#execution-ownership This Windows Go unit calls the owning filesystem operation directly with a temporary directory and its necessary mklink builtin; it installs no consumer and builds or launches no product host. Go test discovers this Test entry without an e2e tag.
+func TestCreateTreatsPathsAsData(t *testing.T) {
+  t.Setenv("TTSC_WINDOWS_JUNCTION_PROBE", "expanded")
+  root := t.TempDir()
+  target := filepath.Join(root, "target & ^ ! %TTSC_WINDOWS_JUNCTION_PROBE% (literal)")
+  link := filepath.Join(root, "link & ^ ! %TTSC_WINDOWS_JUNCTION_PROBE% (literal)")
+  if err := os.Mkdir(target, 0o755); err != nil {
+    t.Fatal(err)
+  }
+  if err := os.WriteFile(filepath.Join(target, "sentinel.txt"), []byte("safe"), 0o644); err != nil {
+    t.Fatal(err)
+  }
+  if err := Create(link, target); err != nil {
+    t.Fatal(err)
+  }
+  t.Cleanup(func() {
+    if err := os.Remove(link); err != nil {
+      t.Error(err)
+    }
+  })
+  got, err := os.ReadFile(filepath.Join(link, "sentinel.txt"))
+  if err != nil {
+    t.Fatal(err)
+  }
+  if string(got) != "safe" {
+    t.Fatalf("junction read %q, want safe", got)
+  }
+  expanded := strings.ReplaceAll(link, "%TTSC_WINDOWS_JUNCTION_PROBE%", "expanded")
+  if _, err := os.Lstat(expanded); !os.IsNotExist(err) {
+    t.Fatalf("environment-expanded alternate %s exists or cannot be observed: %v", expanded, err)
+  }
+}

package/driver/windowsjunction/windowsjunction.go

@@ -7,6 +7,8 @@ import (
   "os"
   "os/exec"
   "strings"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/e2etrace"
 )
 
 const (
@@ -15,6 +17,17 @@ const (
 )
 
 // Create makes link a directory junction that points to target.
+// Call only after selecting the Windows junction boundary; other platforms use
+// their native link implementation.
+//
+// @evidence contracts/common.md#principled-implementation The explicitly Windows-only junction operation keeps mklink semantics separate from other platforms' link creation.
+// @evidence contracts/common.md#clear-and-simple-design One fixed command consumes two environment values and returns its native exit failure.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Path data is not interpolated into cmd syntax or escaped through guessed quoting rules.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the platform precondition and junction purpose following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Required Windows behavior is isolated in the windowsjunction package; fixed cmd arguments and delayed environment expansion preserve path metacharacters as data, while callers select this boundary explicitly.
+// @evidence contracts/performance.md#bound-retention-and-release-resources This invocation owns one cmd child and its captured output until CombinedOutput joins it; returned errors retain only trimmed output text. Captured bytes grow with command output and there is no explicit timeout or output cap.
+// @evidenceExclude contracts/performance.md#efficient-algorithms One cmd.exe invocation with a constant command; there is no loop.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each junction is a distinct filesystem effect, so nothing is reusable between calls.
 func Create(link, target string) error {
   // mklink is a cmd.exe builtin. Feed a constant command over stdin and use
   // delayed environment expansion so Go never has to quote a command string
@@ -29,7 +42,10 @@ func Create(link, target string) error {
     linkEnvironment+"="+link,
     targetEnvironment+"="+target,
   )
-  if out, err := cmd.CombinedOutput(); err != nil {
+  observation := e2etrace.BeginCommand(cmd, "CombinedOutput")
+  out, err := cmd.CombinedOutput()
+  observation.Result(err)
+  if err != nil {
     return fmt.Errorf(
       "mklink /J failed: %v: %s",
       err,

package/go.mod

@@ -2,10 +2,9 @@ module github.com/samchon/ttsc/packages/ttsc
 
 go 1.26
 
-// Every shim sub-module is wired up via the sibling go.work file together
-// with the local typescript-go checkout under ../../third_party/typescript-go.
-// Tagged upstream versions can replace these local wires when the shim API
-// stabilizes.
+// Maintained shim sub-modules are resolved by these package-local replacements.
+// Their pinned typescript-go dependency is resolved through the Go module cache;
+// a sibling go.work or local upstream checkout is not required.
 replace (
 	github.com/microsoft/typescript-go/shim/ast => ./shim/ast
 	github.com/microsoft/typescript-go/shim/astnav => ./shim/astnav
@@ -18,6 +17,7 @@ replace (
 	github.com/microsoft/typescript-go/shim/parser => ./shim/parser
 	github.com/microsoft/typescript-go/shim/printer => ./shim/printer
 	github.com/microsoft/typescript-go/shim/scanner => ./shim/scanner
+	github.com/microsoft/typescript-go/shim/stringutil => ./shim/stringutil
 	github.com/microsoft/typescript-go/shim/tsoptions => ./shim/tsoptions
 	github.com/microsoft/typescript-go/shim/tspath => ./shim/tspath
 	github.com/microsoft/typescript-go/shim/vfs => ./shim/vfs
@@ -27,7 +27,6 @@ replace (
 
 require (
 	github.com/microsoft/typescript-go/shim/ast v0.0.0
-	github.com/microsoft/typescript-go/shim/astnav v0.0.0
 	github.com/microsoft/typescript-go/shim/bundled v0.0.0
 	github.com/microsoft/typescript-go/shim/checker v0.0.0
 	github.com/microsoft/typescript-go/shim/compiler v0.0.0
@@ -36,19 +35,20 @@ require (
 	github.com/microsoft/typescript-go/shim/parser v0.0.0
 	github.com/microsoft/typescript-go/shim/printer v0.0.0
 	github.com/microsoft/typescript-go/shim/scanner v0.0.0
+	github.com/microsoft/typescript-go/shim/stringutil v0.0.0
 	github.com/microsoft/typescript-go/shim/tsoptions v0.0.0
 	github.com/microsoft/typescript-go/shim/tspath v0.0.0
 	github.com/microsoft/typescript-go/shim/vfs v0.0.0
 	github.com/microsoft/typescript-go/shim/vfs/cachedvfs v0.0.0
 	github.com/microsoft/typescript-go/shim/vfs/osvfs v0.0.0
-	golang.org/x/sys v0.43.0
+	golang.org/x/sys v0.46.0
 )
 
 require (
-	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
-	github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157 // indirect
+	github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
 )

package/go.sum

@@ -1,22 +1,22 @@
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+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-20260429010842-56ab4af42157 h1:llOMPhKDiQ+UEJiAaQuuWaJOTg5V7tNNTEf9JPWoYSY=
-github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157/go.mod h1:m8YA0PMC7ti0GW0RI05D6fEcjQeu98XVS+FWF+VDW2k=
+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/peter-evans/patience v0.3.0 h1:rX0JdJeepqdQl1Sk9c9uvorjYYzL2TfgLX1adqYm9cA=
 github.com/peter-evans/patience v0.3.0/go.mod h1:Kmxu5sY1NmBLFSStvXjX1wS9mIv7wMcP/ubucyMOAu0=
 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.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+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/internal/cwd/cwd.go

@@ -4,6 +4,19 @@ import "fmt"
 
 // Resolve returns an explicit working directory override or asks the host OS
 // for the current process directory.
+//
+// The override is preserved without validation or absolutization; the command
+// that consumes it owns those policies. When no override is supplied, getwd
+// must be a valid host directory reader. Its failure retains the wrapped cause.
+//
+// @evidence contracts/common.md#principled-implementation An explicit override wins; otherwise the injected host reader supplies the actual process directory and its error is wrapped without losing identity.
+// @evidence contracts/common.md#clear-and-simple-design This boundary chooses the directory source only; path validation and project anchoring remain with the consuming command.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The reader is an explicit dependency, not a replaced global; override precedence is the CLI contract rather than a fixture exception.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state preservation, the conditional reader precondition and wrapped failure effects under the documentation skill's ownership and rationale guidance.
+// @evidence contracts/portability.md#os-neutral-implementation The supplied host reader owns native directory discovery. Resolve preserves native spelling rather than imposing separators or inferring a filesystem case policy.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Resolve retains no directory handle or cache; the injected reader owns its acquisition and cleanup, and returned directory/error values belong to the caller.
+// @evidence contracts/performance.md#efficient-algorithms A nonempty override returns directly. Otherwise one injected directory read supplies its own native cost; failure formatting includes the returned error's text and formatting behavior, not just the fixed branch count.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call selects the supplied override or current reader result; Resolve owns no process-directory snapshot or validity interval for cross-call reuse.
 func Resolve(override string, getwd func() (string, error)) (string, error) {
   if override != "" {
     return override, nil