ttsc 0.33.0 → 0.34.0

package/tools/shim_audit/baseline.json

@@ -15,10 +15,9 @@
     "ESCAPE|checker|IntrinsicType",
     "ESCAPE|checker|LiteralType",
     "ESCAPE|checker|MappedType",
-    "ESCAPE|checker|NodeBuilder",
-    "ESCAPE|checker|NodeBuilderContext",
     "ESCAPE|checker|ObjectType",
     "ESCAPE|checker|ReverseMappedType",
+    "ESCAPE|checker|SignatureId",
     "ESCAPE|checker|StringMappingType",
     "ESCAPE|checker|StructuredType",
     "ESCAPE|checker|SubstitutionType",
@@ -35,7 +34,7 @@
     "ESCAPE|checker|UnionReduction",
     "ESCAPE|checker|UnionType",
     "ESCAPE|checker|UniqueESSymbolType",
-    "ESCAPE|checker|VerbosityContext",
+    "ESCAPE|core|CheckerLifetime",
     "ESCAPE|core|LimitedSemaphore",
     "ESCAPE|core|ModuleDetectionKind",
     "ESCAPE|core|NewLineKind",
@@ -75,6 +74,8 @@
     "FUNC|ast|EqualDiagnostics",
     "FUNC|ast|EqualDiagnosticsNoRelatedInfo",
     "FUNC|ast|EscapeAllInternalSymbolNames",
+    "FUNC|ast|EscapeInternalSymbolName",
+    "FUNC|ast|EscapeSymbolName",
     "FUNC|ast|ExpressionIsAlias",
     "FUNC|ast|FindAncestor",
     "FUNC|ast|FindAncestorKind",
@@ -302,7 +303,6 @@
     "FUNC|ast|IsIdentifier",
     "FUNC|ast|IsIdentifierName",
     "FUNC|ast|IsIfStatement",
-    "FUNC|ast|IsImplicitlyExportedJSTypeAlias",
     "FUNC|ast|IsImportAttribute",
     "FUNC|ast|IsImportAttributes",
     "FUNC|ast|IsImportCall",
@@ -665,6 +665,7 @@
     "FUNC|diagnosticwriter|WriteFormatDiagnostics",
     "FUNC|execute/incremental|ComputeHash",
     "FUNC|execute/incremental|GetMTime",
+    "FUNC|execute/incremental|IsBuildInfoFileNameDefaultLibrary",
     "FUNC|printer|FormatGeneratedName",
     "FUNC|printer|GetDefaultIndentSize",
     "FUNC|printer|GetEmitContext",

package/tools/shim_audit/go.mod

@@ -1,10 +1,10 @@
 module github.com/samchon/ttsc/packages/ttsc/tools/shim_audit
 
-go 1.26
+go 1.27
 
-require golang.org/x/tools v0.43.0
+require golang.org/x/tools v0.52.0
 
 require (
-	golang.org/x/mod v0.34.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/mod v0.42.0 // indirect
+	golang.org/x/sync v0.24.0 // indirect
 )

package/tools/shim_audit/go.sum

@@ -1,8 +1,8 @@
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
-golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
-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/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
-golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
+golang.org/x/mod v0.42.0 h1:ICeL3t2L30ljSPHHxDnR4fqVcBt/zR2zJAb9juavmQg=
+golang.org/x/mod v0.42.0/go.mod h1:u5fzIrRInkL8MaO1cbRkUHT64v303YIT5KEqpNr7jRs=
+golang.org/x/sync v0.24.0 h1:iqiDrGoDgyuvAKrhLQthUEzU/R378N78gXbBjxed7oA=
+golang.org/x/sync v0.24.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
+golang.org/x/tools v0.52.0 h1:ryxg4U63oaUYk7uOLTF37n43f4qgtGvqV4Ioit1BaEs=
+golang.org/x/tools v0.52.0/go.mod h1:ItcP5UNaVGG+Yc4eIYmaFLNJ4soEopkx5Y2d4lcEurs=

package/tools/shim_audit/linkname_signatures.go

@@ -0,0 +1,178 @@
+package main
+
+import (
+  "errors"
+  "fmt"
+  "go/ast"
+  "go/types"
+  "io/fs"
+  "path/filepath"
+  "sort"
+  "strings"
+
+  "golang.org/x/tools/go/packages"
+)
+
+// checkLinknameSignatures fails when a bodyless //go:linkname declaration in a
+// shim disagrees with the signature of the compiler function it names, a
+// method's receiver counting as the first parameter. The Go toolchain links
+// such a pair without complaint and the mismatch surfaces only as corrupted
+// arguments at run time, so a compiler bump that changes a linked signature
+// must fail here instead. Every shim module below shimRoot is loaded with its
+// dependencies, so the target is checked against the pinned compiler's types.
+//
+// Adapted from Danny Wilson's TypeScript 7.1 port (#1727).
+func checkLinknameSignatures(shimRoot string) error {
+  var dirs []string
+  err := filepath.WalkDir(shimRoot, func(path string, entry fs.DirEntry, err error) error {
+    if err != nil {
+      return err
+    }
+    if !entry.IsDir() && entry.Name() == "go.mod" {
+      dirs = append(dirs, filepath.Dir(path))
+    }
+    return nil
+  })
+  if err != nil {
+    return err
+  }
+  sort.Strings(dirs)
+  var problems []string
+  for _, dir := range dirs {
+    found, err := linknameSignatureProblems(dir)
+    if err != nil {
+      return err
+    }
+    problems = append(problems, found...)
+  }
+  if len(problems) > 0 {
+    return fmt.Errorf("go:linkname declarations disagree with their targets:\n  %s", strings.Join(problems, "\n  "))
+  }
+  return nil
+}
+
+// linknameSignatureProblems reports every mismatched bodyless linkname
+// declaration of the package rooted at dir.
+func linknameSignatureProblems(dir string) ([]string, error) {
+  loaded, err := packages.Load(&packages.Config{
+    Dir:  dir,
+    Mode: packages.NeedName | packages.NeedSyntax | packages.NeedTypes | packages.NeedTypesInfo | packages.NeedImports | packages.NeedDeps,
+  }, ".")
+  if err != nil {
+    return nil, fmt.Errorf("load %s: %w", dir, err)
+  }
+  all := map[string]*types.Package{}
+  var loadErrors []error
+  packages.Visit(loaded, nil, func(pkg *packages.Package) {
+    if pkg.Types != nil {
+      all[pkg.PkgPath] = pkg.Types
+    }
+    for _, e := range pkg.Errors {
+      loadErrors = append(loadErrors, e)
+    }
+  })
+  if err := errors.Join(loadErrors...); err != nil {
+    return nil, fmt.Errorf("load %s: %w", dir, err)
+  }
+  var problems []string
+  for _, pkg := range loaded {
+    for _, file := range pkg.Syntax {
+      links := map[string]string{}
+      for _, group := range file.Comments {
+        for _, comment := range group.List {
+          if fields := strings.Fields(comment.Text); len(fields) == 3 && fields[0] == "//go:linkname" {
+            links[fields[1]] = fields[2]
+          }
+        }
+      }
+      for _, decl := range file.Decls {
+        fn, ok := decl.(*ast.FuncDecl)
+        if !ok || fn.Body != nil || fn.Recv != nil {
+          continue
+        }
+        target, linked := links[fn.Name.Name]
+        if !linked {
+          continue
+        }
+        position := pkg.Fset.Position(fn.Pos())
+        local := pkg.TypesInfo.Defs[fn.Name].Type().(*types.Signature)
+        want, err := linknameTargetSignature(all, target)
+        if err != nil {
+          problems = append(problems, fmt.Sprintf("%s: %s -> %s: %v", position, fn.Name.Name, target, err))
+          continue
+        }
+        if mismatch := compareLinkedSignatures(local, want); mismatch != "" {
+          problems = append(problems, fmt.Sprintf("%s: %s -> %s: %s", position, fn.Name.Name, target, mismatch))
+        }
+      }
+    }
+  }
+  return problems, nil
+}
+
+// linknameTargetSignature resolves "path.name" or "path.(*T).name" against the
+// loaded dependency graph. A method's receiver becomes the first parameter.
+func linknameTargetSignature(all map[string]*types.Package, target string) (*types.Signature, error) {
+  slash := strings.LastIndexByte(target, '/')
+  dot := strings.IndexByte(target[slash+1:], '.')
+  if dot < 0 {
+    return nil, errors.New("malformed target")
+  }
+  path, rest := target[:slash+1+dot], target[slash+1+dot+1:]
+  pkg := all[path]
+  if pkg == nil {
+    return nil, fmt.Errorf("package %s is not compiled into the bridge", path)
+  }
+  if !strings.HasPrefix(rest, "(") {
+    fn, ok := pkg.Scope().Lookup(rest).(*types.Func)
+    if !ok {
+      return nil, fmt.Errorf("no function %s", rest)
+    }
+    return fn.Signature(), nil
+  }
+  closing := strings.IndexByte(rest, ')')
+  if closing < 0 || closing+2 > len(rest) {
+    return nil, errors.New("malformed method target")
+  }
+  receiver, name := strings.TrimPrefix(rest[1:closing], "*"), rest[closing+2:]
+  typeName, ok := pkg.Scope().Lookup(receiver).(*types.TypeName)
+  if !ok {
+    return nil, fmt.Errorf("no type %s", receiver)
+  }
+  object, _, _ := types.LookupFieldOrMethod(types.NewPointer(typeName.Type()), true, pkg, name)
+  method, ok := object.(*types.Func)
+  if !ok {
+    return nil, fmt.Errorf("no method %s", name)
+  }
+  signature := method.Signature()
+  params := []*types.Var{signature.Recv()}
+  for i := range signature.Params().Len() {
+    params = append(params, signature.Params().At(i))
+  }
+  return types.NewSignatureType(nil, nil, nil, types.NewTuple(params...), signature.Results(), signature.Variadic()), nil
+}
+
+// compareLinkedSignatures describes the first difference between the local
+// declaration and its target, or returns "" when they are identical.
+func compareLinkedSignatures(local, want *types.Signature) string {
+  if local.Params().Len() != want.Params().Len() {
+    return fmt.Sprintf("%d parameters, target has %d (%s)", local.Params().Len(), want.Params().Len(), want)
+  }
+  if local.Results().Len() != want.Results().Len() {
+    return fmt.Sprintf("%d results, target has %d (%s)", local.Results().Len(), want.Results().Len(), want)
+  }
+  for i := range local.Params().Len() {
+    if !types.Identical(local.Params().At(i).Type(), want.Params().At(i).Type()) {
+      return fmt.Sprintf("parameter %d is %s, target has %s", i, local.Params().At(i).Type(), want.Params().At(i).Type())
+    }
+  }
+  for i := range local.Results().Len() {
+    if !types.Identical(local.Results().At(i).Type(), want.Results().At(i).Type()) {
+      return fmt.Sprintf("result %d is %s, target has %s", i, local.Results().At(i).Type(), want.Results().At(i).Type())
+    }
+  }
+  if local.Variadic() != want.Variadic() {
+    return "variadic parameter differs from the target"
+  }
+  return ""
+}

package/tools/shim_audit/linkname_signatures_match_their_targets_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+  "os"
+  "path/filepath"
+  "strings"
+  "testing"
+)
+
+// Verifies the linkname gate refuses a bodyless go:linkname declaration whose
+// signature differs from the function it names.
+//
+// The toolchain links such a pair silently and the mismatch corrupts arguments
+// only at run time, which is the failure a compiler bump can introduce.
+//
+//  1. Build a temporary compiler module with an internal package and a bridge
+//     module below a shim root linking one function and one method of it.
+//  2. Require the gate to accept matching declarations.
+//  3. Change a parameter type, then drop a parameter, and require the gate to
+//     name each mismatched declaration.
+//
+// @evidence contracts/testing.md#behavioral-verification checkLinknameSignatures loads a real temporary module through go/packages and is required to accept matching declarations and reject each drifted one by name.
+// @evidence contracts/testing.md#independent-expectations The target signatures and the drifted declarations are authored literals in the fixture; the expected names come from the fixture, not from the gate's output.
+// @evidence contracts/testing.md#distinguishing-cases A matching function and receiver method pass, a changed parameter type fails, and a missing parameter fails, each with its own expected outcome.
+// @evidence contracts/testing.md#execution-ownership This tools/shim_audit unit writes a temporary module and loads it with the go command in one test process; it reads no repository bridge.
+func TestLinknameSignaturesMatchTheirTargets(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("compiler/go.mod", "module example.com/fixture\n\ngo 1.27\n")
+  write("compiler/internal/target/target.go", "package target\n\ntype Box struct{ n int }\n\nfunc join(a string, b int) string { return a }\n\nfunc (b *Box) grow(n int) int { return b.n + n }\n")
+  bridge := func(joinParams, growParams string) string {
+    return "package bridge\n\nimport (\n  _ \"unsafe\"\n\n  \"example.com/fixture/internal/target\"\n)\n\n" +
+      "//go:linkname Join example.com/fixture/internal/target.join\nfunc Join(" + joinParams + ") string\n\n" +
+      "//go:linkname Grow example.com/fixture/internal/target.(*Box).grow\nfunc Grow(" + growParams + ") int\n"
+  }
+  t.Setenv("GOWORK", "off")
+  t.Setenv("GOFLAGS", "-mod=mod")
+
+  write("shim/bridge/go.mod", "module example.com/fixture/bridge\n\ngo 1.27\n\nrequire example.com/fixture v0.0.0\n\nreplace example.com/fixture => ../../compiler\n")
+  write("shim/bridge/bridge.go", bridge("a string, b int", "b *target.Box, n int"))
+  if err := checkLinknameSignatures(filepath.Join(root, "shim")); err != nil {
+    t.Fatalf("matching declarations rejected: %v", err)
+  }
+
+  write("shim/bridge/bridge.go", bridge("a string, b string", "b *target.Box"))
+  err := checkLinknameSignatures(filepath.Join(root, "shim"))
+  if err == nil {
+    t.Fatal("drifted declarations accepted")
+  }
+  for _, want := range []string{"Join -> example.com/fixture/internal/target.join: parameter 1 is string, target has int", "Grow -> example.com/fixture/internal/target.(*Box).grow: 1 parameters, target has 2"} {
+    if !strings.Contains(err.Error(), want) {
+      t.Errorf("missing %q in %v", want, err)
+    }
+  }
+}

package/tools/shim_audit/linkname_targets_follow_the_audited_compiler_test.go

@@ -0,0 +1,38 @@
+package main
+
+import "testing"
+
+// Verifies the reachability scan reads linkname targets of the audited
+// compiler target only.
+//
+// The TypeScript 7.1 bridges link into github.com/microsoft/TypeScript/tsc,
+// while the 7.0 shims link into typescript-go. Recognizing the other target's
+// links would mark symbols reachable that the audited shims cannot name.
+//
+//  1. Build the scanner for the 7.1 internal prefix and match a 7.1 method link
+//     and a nested-package function link.
+//  2. Require both scanners to reject a link into the other compiler.
+//
+// @evidence contracts/testing.md#behavioral-verification Calls the production newLinknameRe and asserts the captured package suffix and symbol, or the absence of a match, for each line.
+// @evidence contracts/testing.md#independent-expectations The expected suffixes and names are written beside literal linkname lines taken from the two compilers' module paths.
+// @evidence contracts/testing.md#distinguishing-cases A receiver method and a nested-package function must match under 7.1, and each target's scanner must reject the other compiler's otherwise identical link; TestLinknameRe owns the remaining 7.0 shapes.
+// @evidence contracts/testing.md#execution-ownership This tools/shim_audit unit compiles regular expressions in process; it loads no package and starts no process.
+func TestLinknameTargetsFollowTheAuditedCompiler(t *testing.T) {
+  const tsc = "github.com/microsoft/TypeScript/tsc/internal/"
+  scanner := newLinknameRe(tsc)
+  for _, c := range []struct{ line, pkg, name string }{
+    {"//go:linkname checkerGetMinArgumentCount " + tsc + "checker.(*Checker).getMinArgumentCount", "checker", "getMinArgumentCount"},
+    {"//go:linkname From " + tsc + "vfs/cachedvfs.From", "vfs/cachedvfs", "From"},
+  } {
+    m := scanner.FindStringSubmatch(c.line)
+    if m == nil || m[1] != c.pkg || m[2] != c.name {
+      t.Errorf("%q matched %v, want %s.%s", c.line, m, c.pkg, c.name)
+    }
+  }
+  if m := scanner.FindStringSubmatch("//go:linkname From " + defaultInternalPrefix + "vfs/cachedvfs.From"); m != nil {
+    t.Errorf("7.1 scanner matched a 7.0 link: %v", m)
+  }
+  if m := newLinknameRe(defaultInternalPrefix).FindStringSubmatch("//go:linkname From " + tsc + "vfs/cachedvfs.From"); m != nil {
+    t.Errorf("7.0 scanner matched a 7.1 link: %v", m)
+  }
+}

package/tools/shim_audit/main.go

@@ -67,7 +67,11 @@ import (
   "golang.org/x/tools/go/packages"
 )
 
-const internalPrefix = "github.com/microsoft/typescript-go/internal/"
+// defaultInternalPrefix is the TypeScript 7.0 compiler's internal tree.
+const defaultInternalPrefix = "github.com/microsoft/typescript-go/internal/"
+
+// internalPrefix is the internal tree of the target being audited (-internal).
+var internalPrefix = defaultInternalPrefix
 
 // shimDirs maps each full re-export shim directory to its upstream internal
 // package suffix. Kept explicit (rather than globbed) so a new shim dir is a
@@ -202,9 +206,14 @@ func opposite(direction flowDirection) flowDirection {
 
 // linknameRe captures the trailing symbol name of a go:linkname target like
 // `...internal/checker.(*Checker).getMinArgumentCount` or `...checker.foo`.
-var linknameRe = regexp.MustCompile(`(?m)^//go:linkname\s+\S+\s+` +
-  regexp.QuoteMeta("github.com/microsoft/typescript-go/internal/") +
-  `([A-Za-z0-9_/]+)\.(?:\(\*?[A-Za-z0-9_]+\)\.)?([A-Za-z0-9_]+)`)
+var linknameRe = newLinknameRe(defaultInternalPrefix)
+
+// newLinknameRe matches go:linkname targets below one compiler's internal tree.
+func newLinknameRe(prefix string) *regexp.Regexp {
+  return regexp.MustCompile(`(?m)^//go:linkname\s+\S+\s+` +
+    regexp.QuoteMeta(prefix) +
+    `([A-Za-z0-9_/]+)\.(?:\(\*?[A-Za-z0-9_]+\)\.)?([A-Za-z0-9_]+)`)
+}
 
 // scanShimReachable parses every .go file under each shim dir and records the
 // upstream symbols it references.
@@ -869,7 +878,11 @@ func main() {
   baselinePath := flag.String("baseline", "baseline.json", "path to the accepted-gap baseline")
   anchor := flag.String("anchor", "./shim/ast", "module dir anchoring the typescript-go require")
   shimRoot := flag.String("shim", "./shim", "shim root directory")
+  internal := flag.String("internal", defaultInternalPrefix, "internal import prefix of the audited compiler target")
+  neutralWith := flag.String("neutral-with", "", "shim root of another compiler target whose version-neutral API must match")
   flag.Parse()
+  internalPrefix = *internal
+  linknameRe = newLinknameRe(internalPrefix)
 
   // A shim directory that is not registered for audit coverage would silently
   // escape every check — close that hole before doing anything else.
@@ -877,6 +890,18 @@ func main() {
     fmt.Fprintln(os.Stderr, "shim_audit:", err)
     os.Exit(2)
   }
+  // A linked declaration whose signature drifted from its compiler target
+  // still links, then corrupts arguments at run time; refuse it outright.
+  if err := checkLinknameSignatures(*shimRoot); err != nil {
+    fmt.Fprintln(os.Stderr, "shim_audit:", err)
+    os.Exit(2)
+  }
+  if *neutralWith != "" {
+    if err := checkNeutralAPI(*shimRoot, *neutralWith); err != nil {
+      fmt.Fprintln(os.Stderr, "shim_audit:", err)
+      os.Exit(2)
+    }
+  }
 
   r, err := scanShimReachable(*shimRoot)
   if err != nil {

package/tools/shim_audit/neutral_api.go

@@ -0,0 +1,160 @@
+package main
+
+import (
+  "fmt"
+  "go/ast"
+  "go/parser"
+  "go/token"
+  "io/fs"
+  "os"
+  "path/filepath"
+  "sort"
+  "strings"
+)
+
+// neutralFileName is the file in each shim package that declares the
+// version-neutral API: functions that every compiler target declares with
+// identical signatures, so one plugin source compiles on all of them.
+const neutralFileName = "neutral.go"
+
+// neutralFunction is the shape of one exported neutral function that the
+// targets must agree on. Parameter and result types are spelled through each
+// target's own aliases, so the type check belongs to compiling plugin code on
+// every target; this records what the source alone can compare.
+type neutralFunction struct {
+  params   int
+  results  int
+  variadic bool
+}
+
+// checkNeutralAPI fails when the shim roots of two compiler targets declare
+// different version-neutral APIs: a package with a neutral.go in one root and
+// not the other, or a function present in one target only or with a
+// different parameter count, result count or variadic final parameter.
+func checkNeutralAPI(firstRoot string, secondRoot string) error {
+  first, err := readNeutralAPI(firstRoot)
+  if err != nil {
+    return err
+  }
+  second, err := readNeutralAPI(secondRoot)
+  if err != nil {
+    return err
+  }
+  var problems []string
+  packages := map[string]bool{}
+  for pkg := range first {
+    packages[pkg] = true
+  }
+  for pkg := range second {
+    packages[pkg] = true
+  }
+  for _, pkg := range sortedKeys(packages) {
+    a, inFirst := first[pkg]
+    b, inSecond := second[pkg]
+    switch {
+    case !inFirst:
+      problems = append(problems, fmt.Sprintf("%s: neutral API only in %s", pkg, secondRoot))
+      continue
+    case !inSecond:
+      problems = append(problems, fmt.Sprintf("%s: neutral API only in %s", pkg, firstRoot))
+      continue
+    }
+    names := map[string]bool{}
+    for name := range a {
+      names[name] = true
+    }
+    for name := range b {
+      names[name] = true
+    }
+    for _, name := range sortedKeys(names) {
+      x, inA := a[name]
+      y, inB := b[name]
+      switch {
+      case !inA:
+        problems = append(problems, fmt.Sprintf("%s.%s: declared only in %s", pkg, name, secondRoot))
+      case !inB:
+        problems = append(problems, fmt.Sprintf("%s.%s: declared only in %s", pkg, name, firstRoot))
+      case x != y:
+        problems = append(problems, fmt.Sprintf("%s.%s: %d parameters and %d results (variadic %t) in %s, %d and %d (variadic %t) in %s", pkg, name, x.params, x.results, x.variadic, firstRoot, y.params, y.results, y.variadic, secondRoot))
+      }
+    }
+  }
+  if len(problems) > 0 {
+    return fmt.Errorf("version-neutral shim APIs differ between targets:\n  %s", strings.Join(problems, "\n  "))
+  }
+  return nil
+}
+
+// readNeutralAPI maps each package below root that has a neutral.go, by its
+// slash-separated directory, to that file's exported functions.
+func readNeutralAPI(root string) (map[string]map[string]neutralFunction, error) {
+  api := map[string]map[string]neutralFunction{}
+  err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
+    if err != nil {
+      return err
+    }
+    if entry.IsDir() || entry.Name() != neutralFileName {
+      return nil
+    }
+    rel, err := filepath.Rel(root, filepath.Dir(path))
+    if err != nil {
+      return err
+    }
+    source, err := os.ReadFile(path)
+    if err != nil {
+      return err
+    }
+    file, err := parser.ParseFile(token.NewFileSet(), path, source, parser.SkipObjectResolution)
+    if err != nil {
+      return err
+    }
+    functions := map[string]neutralFunction{}
+    for _, decl := range file.Decls {
+      fn, ok := decl.(*ast.FuncDecl)
+      if !ok || fn.Recv != nil || !fn.Name.IsExported() {
+        continue
+      }
+      functions[fn.Name.Name] = neutralFunction{
+        params:   fieldCount(fn.Type.Params),
+        results:  fieldCount(fn.Type.Results),
+        variadic: isVariadic(fn.Type.Params),
+      }
+    }
+    api[filepath.ToSlash(rel)] = functions
+    return nil
+  })
+  return api, err
+}
+
+// fieldCount counts the values a field list declares, so `a, b string` is two.
+func fieldCount(list *ast.FieldList) int {
+  if list == nil {
+    return 0
+  }
+  count := 0
+  for _, field := range list.List {
+    if len(field.Names) == 0 {
+      count++
+    } else {
+      count += len(field.Names)
+    }
+  }
+  return count
+}
+
+func isVariadic(list *ast.FieldList) bool {
+  if list == nil || len(list.List) == 0 {
+    return false
+  }
+  _, ok := list.List[len(list.List)-1].Type.(*ast.Ellipsis)
+  return ok
+}
+
+func sortedKeys(set map[string]bool) []string {
+  keys := make([]string, 0, len(set))
+  for key := range set {
+    keys = append(keys, key)
+  }
+  sort.Strings(keys)
+  return keys
+}

package/tools/shim_audit/neutral_api_must_match_across_targets_test.go

@@ -0,0 +1,74 @@
+package main
+
+import (
+  "os"
+  "path/filepath"
+  "strings"
+  "testing"
+)
+
+// Verifies the neutral-API gate accepts matching targets and names every way
+// two targets' version-neutral APIs can drift apart.
+//
+// One plugin source compiles on every compiler target only when each target's
+// neutral.go declares the same functions with the same arity. Types are spelled
+// through each target's own aliases, so arity is what the source can compare.
+//
+//  1. Write two shim roots whose neutral.go files declare the same functions.
+//  2. Require the gate to accept them, including grouped parameters and a
+//     variadic tail, and to ignore methods and unexported helpers.
+//  3. Drop a function, change an arity, change variadicity and remove a whole
+//     package from one root, and require each drift to be reported by name.
+//
+// @evidence contracts/testing.md#behavioral-verification Calls the production checkNeutralAPI over real temporary files and asserts acceptance or the reported drift lines.
+// @evidence contracts/testing.md#independent-expectations The expected names and counts come from the authored fixture sources, not from the gate's output.
+// @evidence contracts/testing.md#distinguishing-cases A matching pair passes; a missing function, a parameter-count change, a variadic change and a package missing on one side fail; methods and unexported functions must not count.
+// @evidence contracts/testing.md#execution-ownership This tools/shim_audit unit writes temporary files and parses them in process; it loads no module and starts no process.
+func TestNeutralAPIMustMatchAcrossTargets(t *testing.T) {
+  write := func(root, rel, text string) {
+    t.Helper()
+    path := filepath.Join(root, filepath.FromSlash(rel))
+    if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+      t.Fatal(err)
+    }
+    if err := os.WriteFile(path, []byte(text), 0o644); err != nil {
+      t.Fatal(err)
+    }
+  }
+  const base = "package tspath\n\nfunc Compare(c bool, a, b string) int { return 0 }\nfunc Join(parts ...string) string { return \"\" }\nfunc helper() {}\ntype T struct{}\nfunc (T) Method(x int) {}\n"
+  first, second := t.TempDir(), t.TempDir()
+  write(first, "tspath/neutral.go", base)
+  write(second, "tspath/neutral.go", strings.ReplaceAll(base, "c bool, a, b string", "c Policy, a Path, b Path")+"type Policy = bool\ntype Path = string\nfunc extra(y string) {}\n")
+  write(first, "vfs/shim.go", "package vfs\n\nfunc NotNeutral() {}\n")
+  if err := checkNeutralAPI(first, second); err != nil {
+    t.Fatalf("matching APIs rejected: %v", err)
+  }
+
+  write(second, "tspath/neutral.go", "package tspath\n\nfunc Compare(c bool, a string) int { return 0 }\nfunc Join(parts []string) string { return \"\" }\n")
+  write(second, "ast/neutral.go", "package ast\n\nfunc SymbolNameOf(s any) string { return \"\" }\n")
+  write(first, "compiler/neutral.go", "package compiler\n\nfunc Only() {}\n")
+  err := checkNeutralAPI(first, second)
+  if err == nil {
+    t.Fatal("drifted APIs accepted")
+  }
+  for _, want := range []string{
+    "tspath.Compare: 3 parameters and 1 results (variadic false)",
+    "tspath.Join: 1 parameters and 1 results (variadic true)",
+    "ast: neutral API only in " + second,
+    "compiler: neutral API only in " + first,
+  } {
+    if !strings.Contains(err.Error(), want) {
+      t.Errorf("missing %q in %v", want, err)
+    }
+  }
+
+  write(second, "tspath/neutral.go", base)
+  if err := os.Remove(filepath.Join(second, "ast", "neutral.go")); err != nil {
+    t.Fatal(err)
+  }
+  write(first, "compiler/neutral.go", "package compiler\n\nfunc Only() {}\nfunc Gone() {}\n")
+  write(second, "compiler/neutral.go", "package compiler\n\nfunc Only() {}\n")
+  if err := checkNeutralAPI(first, second); err == nil || !strings.Contains(err.Error(), "compiler.Gone: declared only in "+first) {
+    t.Fatalf("dropped function not reported: %v", err)
+  }
+}