ttsc 0.30.4 → 0.31.1

package/tools/shim_audit/main_test.go

@@ -12,6 +12,11 @@ import (
 // TestLinknameRe pins the two //go:linkname target shapes the reachability scan
 // must recognize — a package-level symbol and a (pointer-)receiver method — plus
 // slashed (nested) package suffixes, and rejects non-typescript-go targets.
+//
+// @evidence contracts/testing.md#behavioral-verification The linkname regular expression recognizes package-level and pointer-receiver method targets, including nested package suffixes, and rejects non-typescript-go targets.
+// @evidence contracts/testing.md#independent-expectations The expected package, name and hit values are literal strings written beside each input line.
+// @evidence contracts/testing.md#distinguishing-cases Receiver and plain forms, slashed package suffixes and a foreign target are the decision differences.
+// @evidence contracts/testing.md#execution-ownership TestLinknameRe is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestLinknameRe(t *testing.T) {
   cases := []struct {
     line     string
@@ -47,6 +52,11 @@ func TestLinknameRe(t *testing.T) {
 
 // TestDedupe locks the determinism guarantee: one entry per kind|pkg|symbol,
 // keeping the lexicographically smallest detail, ordered by pkg, kind, symbol.
+//
+// @evidence contracts/testing.md#behavioral-verification dedupe keeps one finding per kind, package and symbol with the lexicographically smallest detail, ordered by package, kind and symbol.
+// @evidence contracts/testing.md#independent-expectations The expected slice is written literally.
+// @evidence contracts/testing.md#distinguishing-cases A duplicate key with a larger detail and distinct kinds and packages show the ordering and tie-break.
+// @evidence contracts/testing.md#execution-ownership TestDedupe is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestDedupe(t *testing.T) {
   in := []finding{
     {"FUNC", "checker", "B", "detail-z"},
@@ -66,6 +76,11 @@ func TestDedupe(t *testing.T) {
 }
 
 // TestTierOf pins the kind→tier mapping the gate and report depend on.
+//
+// @evidence contracts/testing.md#behavioral-verification tierOf maps the six authored finding kinds to their literal confidence tiers; the enum-removal tier is checked by the removal-specific test.
+// @evidence contracts/testing.md#independent-expectations The expected tier numbers are literals from the audit's stated tier policy.
+// @evidence contracts/testing.md#distinguishing-cases The six rows include tier-one, tier-two, tier-three and default-tier cases; their authored mapping detects a changed result for those kinds.
+// @evidence contracts/testing.md#execution-ownership TestTierOf is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestTierOf(t *testing.T) {
   cases := map[string]int{"ENUM": 1, "FUNC": 2, "PRODUCER": 2, "ESCAPE": 3, "ENUM?": 4, "UNEXPORTED": 4}
   for kind, want := range cases {
@@ -77,6 +92,11 @@ func TestTierOf(t *testing.T) {
 
 // TestIndexInternalPackages proves dependency-only internal type packages stay
 // available to the named producer-contract scanner and load failures stay fatal.
+//
+// @evidence contracts/testing.md#behavioral-verification indexInternalPackages keeps dependency-only internal type packages available and reports a package whose types are missing as a closed failure.
+// @evidence contracts/testing.md#independent-expectations The expected index entries and error map follow from the synthetic packages the test builds.
+// @evidence contracts/testing.md#distinguishing-cases A loaded dependency and the same dependency with nil Types contrast success and failure.
+// @evidence contracts/testing.md#execution-ownership TestIndexInternalPackages is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestIndexInternalPackages(t *testing.T) {
   dependencyTypes := types.NewPackage(internalPrefix+"lsp/lsproto", "lsproto")
   dependency := &packages.Package{
@@ -101,6 +121,11 @@ func TestIndexInternalPackages(t *testing.T) {
 }
 
 // TestCommonPrefix covers the helper feeding the abbreviation fallback.
+//
+// @evidence contracts/testing.md#behavioral-verification commonPrefix returns the longest shared prefix of the supplied names, the single name itself, and the empty string for no overlap or no input.
+// @evidence contracts/testing.md#independent-expectations Each expected prefix is a literal beside its input.
+// @evidence contracts/testing.md#distinguishing-cases Shared, single, disjoint and empty inputs are the boundary cases.
+// @evidence contracts/testing.md#execution-ownership TestCommonPrefix is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestCommonPrefix(t *testing.T) {
   cases := []struct {
     in   []string
@@ -123,6 +148,11 @@ func TestCommonPrefix(t *testing.T) {
 // (longest wins) and the abbreviation fallback that closes the untyped+
 // unprefixed blind spot (OuterExpressionKinds' OEKExcludeJSDocTypeAssertion),
 // plus the negative twins that must NOT over-attach.
+//
+// @evidence contracts/testing.md#behavioral-verification Untyped constants attach to their enum type by longest type-name prefix and, failing that, by a shared abbreviation prefix, while unrelated constants stay unattached.
+// @evidence contracts/testing.md#independent-expectations The expected attachments are literal maps written from the enum naming convention, for example OEK constants joining OuterExpressionKinds.
+// @evidence contracts/testing.md#distinguishing-cases Negative cases that must not over-attach sit beside the attaching ones.
+// @evidence contracts/testing.md#execution-ownership TestAttachUntypedConsts is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestAttachUntypedConsts(t *testing.T) {
   t.Run("abbreviation fallback (OEK blind spot)", func(t *testing.T) {
     enums := []string{"OuterExpressionKinds", "Kind"}
@@ -183,6 +213,11 @@ func TestAttachUntypedConsts(t *testing.T) {
 
 // TestIsReachable covers the structural recursion plus the decisive case: an
 // internal named type is reachable only when the shim exposes it.
+//
+// @evidence contracts/testing.md#behavioral-verification isReachable treats basic types and composites of them as reachable and an internal named type as reachable only after the shim exposes it.
+// @evidence contracts/testing.md#independent-expectations The expected booleans follow from the reachability rule the audit documents, using synthetic types.
+// @evidence contracts/testing.md#distinguishing-cases The same internal named type is checked unexposed and exposed.
+// @evidence contracts/testing.md#execution-ownership TestIsReachable is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestIsReachable(t *testing.T) {
   fresh := func() map[types.Type]bool { return map[types.Type]bool{} }
   r := reachable{}

package/tools/shim_audit/producer_exemptions_require_rationale_test.go

@@ -10,6 +10,11 @@ import "testing"
 //  1. Evaluate the same producer gap with no exemption and an empty exemption.
 //  2. Supply a reasoned public-root exemption and accept the unrelated function gap.
 //  3. Confirm only the deliberate classification passes both gate classes.
+//
+// @evidence contracts/testing.md#behavioral-verification A producer gap passes the gate only with a non-empty rationale; an absent or empty exemption leaves it failing.
+// @evidence contracts/testing.md#independent-expectations The expected gap and new-gap counts are literal numbers for the absent, empty and reasoned exemptions.
+// @evidence contracts/testing.md#distinguishing-cases Absent, empty and reasoned exemptions are three inputs for the same gap.
+// @evidence contracts/testing.md#execution-ownership TestProducerExemptionsRequireRationale is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestProducerExemptionsRequireRationale(t *testing.T) {
   surface := newProducerSurface()
   surface.add(flowConsume, flowType{pkg: "fixture", name: "Root"}, "fixture.UseRoot")

package/tools/shim_audit/producer_surface_includes_exposed_methods_test.go

@@ -19,6 +19,11 @@ import (
 //  4. Remove the receiver root and confirm its result no longer counts.
 //  5. Restore it explicitly, then prove a rootless self-cycle still fails.
 //  6. Prove reachable receivers do not legitimize argument/result cycles.
+//
+// @evidence contracts/testing.md#behavioral-verification Producer closure includes exported methods and canonical aliases: removing the producer makes the consumer a gap, an alias and a canonical producer close the same edge, and a rootless self-cycle still fails.
+// @evidence contracts/testing.md#independent-expectations The expected gaps are literal type and symbol names in the synthetic fixture package.
+// @evidence contracts/testing.md#distinguishing-cases Present/removed method producers, canonical aliases, receiver roots, self-cycles and argument/result cycles have independently authored outcomes; these are related fixture transitions, not a claim that every step changes exactly one input.
+// @evidence contracts/testing.md#execution-ownership TestProducerSurfaceIncludesExposedMethods is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestProducerSurfaceIncludesExposedMethods(t *testing.T) {
   build := func(includeProducer bool) (reachable, map[string]*packages.Package) {
     pkg := types.NewPackage(internalPrefix+"fixture", "fixture")

package/tools/shim_audit/producer_surface_rejects_unproducible_reference_test.go

@@ -21,6 +21,11 @@ import (
 //  4. Remove a method consumer's producer and confirm that gap appears too.
 //  5. Repeat through recursive named callbacks and containers without hanging.
 //  6. Prove package-operation cycles fail until an independent root is added.
+//
+// @evidence contracts/testing.md#behavioral-verification Producer closure rejects a consumed reference after its only producer is removed, including through callbacks, recursive named callbacks and package-operation cycles.
+// @evidence contracts/testing.md#independent-expectations The expected gaps are literal type-keyed findings for the fixture source.
+// @evidence contracts/testing.md#distinguishing-cases Input-only objects, removed package producers, removed method producers and cycles are separate cases that must each fail until a root is added.
+// @evidence contracts/testing.md#execution-ownership TestProducerSurfaceRejectsUnproducibleReference is a Go unit test of the shim_audit tool package: it calls the analysis helper in-process on literal or synthetic type-checker values and starts no Go toolchain run.
 func TestProducerSurfaceRejectsUnproducibleReference(t *testing.T) {
   source := `package fixture
 import inner "github.com/microsoft/typescript-go/internal/fixture"

package/tools/shim_audit/shim_dir_coverage_rejects_unregistered_shims_test.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+  "os"
+  "path/filepath"
+  "strings"
+  "testing"
+)
+
+// Verifies the coverage gate names every unregistered shim directory at any depth.
+//
+// A shim directory that is missing from the audit's registries would silently
+// escape every closure check, so the gate must fail for it, including when it
+// is nested, and must stay quiet for registered, bridge and test-only
+// directories.
+//
+//  1. Build a temporary shim root with registered, bridge and test-only folders.
+//  2. Require the gate to accept it, and the reachability scan to see a bridge
+//     linkname target.
+//  3. Add an unregistered top-level shim and an unregistered nested shim and
+//     require the error to name both.
+//
+// @evidence contracts/testing.md#behavioral-verification checkShimDirCoverage and scanShimReachable run over a temporary shim tree: the registered tree passes, the scan records the astnav bridge's linkname target, and two unregistered directories make the gate fail.
+// @evidence contracts/testing.md#independent-expectations The registered directory names (ast, vfs/osvfs, astnav) come from the documented audit registries, the unregistered names newpkg and vfs/extra are authored here, and the expected symbol GetTouchingToken is the literal linkname target written into the fixture.
+// @evidence contracts/testing.md#distinguishing-cases Registered full re-export, nested registered package, registered bridge, a directory holding only a _test.go file, an unregistered top-level package and an unregistered nested package each get a distinct expected outcome; only the last two may be reported.
+// @evidence contracts/testing.md#execution-ownership This source unit runs in tools/shim_audit through go test in one process using temporary files and the audit's own scanner; it starts no subprocess and loads no typescript-go packages.
+func TestCheckShimDirCoverageRejectsUnregisteredShims(t *testing.T) {
+  root := t.TempDir()
+  write := func(relative, text string) {
+    t.Helper()
+    filename := filepath.Join(root, filepath.FromSlash(relative))
+    if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
+      t.Fatal(err)
+    }
+    if err := os.WriteFile(filename, []byte(text), 0o644); err != nil {
+      t.Fatal(err)
+    }
+  }
+  write("ast/shim.go", "package ast\n")
+  write("vfs/osvfs/shim.go", "package osvfs\n")
+  write("astnav/bridge.go", "package astnav\n\n//go:linkname GetTouchingToken github.com/microsoft/typescript-go/internal/astnav.GetTouchingToken\nfunc GetTouchingToken()\n")
+  write("ast/test/only_test.go", "package ast_test\n")
+
+  if err := checkShimDirCoverage(root); err != nil {
+    t.Fatalf("registered tree rejected: %v", err)
+  }
+  reachable, err := scanShimReachable(root)
+  if err != nil {
+    t.Fatal(err)
+  }
+  if !reachable.has("astnav", "GetTouchingToken") {
+    t.Fatal("the astnav bridge's linkname target was not recorded")
+  }
+
+  write("newpkg/shim.go", "package newpkg\n")
+  write("vfs/extra/shim.go", "package extra\n")
+  err = checkShimDirCoverage(root)
+  if err == nil {
+    t.Fatal("unregistered shim directories were accepted")
+  }
+  for _, name := range []string{"newpkg", "vfs/extra"} {
+    if !strings.Contains(err.Error(), name) {
+      t.Fatalf("error does not name %q: %v", name, err)
+    }
+  }
+  for _, name := range []string{"ast/test", "vfs/osvfs", "astnav"} {
+    if strings.Contains(err.Error(), name) {
+      t.Fatalf("error names a directory that is allowed (%q): %v", name, err)
+    }
+  }
+}

package/utility/command.go

@@ -0,0 +1,48 @@
+package utility
+
+import (
+  "fmt"
+  "io"
+)
+
+// RunCommandWithIO dispatches the standalone utility plugin command using the
+// package identity and version supplied by its entrypoint. stdout and stderr
+// are borrowed non-nil writers; build, transform and check retain their existing
+// host flags, project loading, plugin registration and command status policies.
+//
+// Metadata aliases use only the first argument and do not load a project.
+// Empty argv and unknown first arguments return usage status 2. Metadata and
+// usage writes retain the entrypoints' existing unchecked write-error behavior.
+//
+// Dispatch interprets argv and borrowed streams as Go values. Filesystem
+// operations, compiler processing and Program leases remain with the host
+// operations; this adapter keeps no cache or resources across calls.
+//
+// @evidence contracts/common.md#principled-implementation The first argv token selects the same metadata aliases and three host operations as the standalone entrypoints; remaining arguments and invocation writers pass unchanged to their actual WithIO owners.
+// @evidence contracts/common.md#clear-and-simple-design One command switch owns parsing for all three real utility plugin entrypoints; compiler work remains in the existing build, transform and check operations.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts All three production entrypoints call this dispatch; no test callback or alternate predicate duplicates command classification, and unknown tokens do not fall through to a compiler operation.
+// @evidence contracts/common.md#meaningful-documentation Native prose states package metadata provenance, borrowed writer requirements, no-project aliases, usage status and the retained metadata write-error limitation separately from these tags.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This dispatcher borrows argv and writers without acquiring an independent handle or program lease; writer-retained output and host-owned program/artifact lifetimes belong to their existing owners, with no dispatcher-held historical state.
+// @evidence contracts/performance.md#efficient-algorithms A bounded command switch selects from the first token and passes a slice of remaining argv without copying it. Metadata and usage formatting scale with package/version/token bytes and the supplied writer's work; host commands additionally incur their delegated argument, compiler and output costs, rather than constant work implied by the switch size.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The dispatcher owns no keyed producer, result cache or in-flight request coordinator; selected host operations retain responsibility for their compiler-generation and hook reuse.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Dispatches on args[0] and writes usage text to the supplied writers; the commands it dispatches to own their path and process handling.
+func RunCommandWithIO(packageName, version string, args []string, stdout, stderr io.Writer) int {
+  if len(args) == 0 {
+    fmt.Fprintf(stderr, "%s: command required (expected build|transform|check|version)\n", packageName)
+    return 2
+  }
+  switch args[0] {
+  case "-v", "--version", "version":
+    fmt.Fprintf(stdout, "%s %s\n", packageName, version)
+    return 0
+  case "build":
+    return RunBuildWithIO(args[1:], stdout, stderr)
+  case "transform":
+    return RunTransformWithIO(args[1:], stdout, stderr)
+  case "check":
+    return RunCheckWithIO(args[1:], stdout, stderr)
+  default:
+    fmt.Fprintf(stderr, "%s: unknown command %q\n", packageName, args[0])
+    return 2
+  }
+}

package/utility/flags_gen.go

@@ -1,6 +1,6 @@
 // Code generated by packages/ttsc/scripts/gen-flags.mts. DO NOT EDIT.
 //
-// Source of truth: packages/ttsc/src/flags/schema.ts.
+// Source of truth: packages/ttsc/src/flags/FLAG_SCHEMA.ts.
 // Regenerate with:    pnpm format
 // Verify in CI with:  node packages/ttsc/scripts/check-flags.cjs
 
@@ -10,7 +10,7 @@ package utility
 // value is true when the flag carries a separate value token (--flag VALUE
 // or --flag=VALUE) and false when the flag is boolean (--flag).
 //
-// Generated from packages/ttsc/src/flags/schema.ts. Edit the schema, not
+// Generated from packages/ttsc/src/flags/FLAG_SCHEMA.ts. Edit the schema, not
 // this file.
 var HostFlagAllowList = map[string]bool{
   "checkers":       true,