fix(paths): commit resolution to the best pattern and hoist the walk closure

samchon · claude · samchon · commit 98d229dc5d6d · 2026-07-02T21:51:33.000+09:00
Self-review follow-ups on the same rewriter, both aligning it further with its oracles: - resolveSource fell through to weaker patterns when the best-precedence match's targets named no program source, rewriting the import at a module tsc never resolved. tsc's tryLoadModuleUsingPaths commits to the single matched pattern -- when its substitutions fail, paths resolution fails -- so the rewriter now stops there and leaves the specifier untouched. - visitModuleSpecifiers handed ForEachChild a fresh closure at every node, one allocation per AST node per apply pass across the whole program. The recursion now runs through one closure per walk, the same discipline linthost's walkDescendants documents for exactly this reason. Refs #310. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AivFfPoUxoU26Dko5Jbm21
diff --git a/packages/paths/driver/paths.go b/packages/paths/driver/paths.go
@@ -122,40 +122,49 @@ func (r *rewriter) apply(file *shimast.SourceFile) {
 // visit for every string-literal module specifier it finds. Covered nodes
 // include import/export declarations, require() calls, dynamic import()
 // expressions, import-equals declarations, and import-type nodes.
+//
+// The recursion runs through one closure created per walk, not one per node:
+// handing ForEachChild a fresh closure at every node would allocate once per
+// AST node across the whole program on every apply pass.
 func visitModuleSpecifiers(node *shimast.Node, visit func(*shimast.Node)) {
   if node == nil {
     return
   }
-  switch node.Kind {
-  case shimast.KindImportDeclaration:
-    visit(node.AsImportDeclaration().ModuleSpecifier)
-  case shimast.KindExportDeclaration:
-    visit(node.AsExportDeclaration().ModuleSpecifier)
-  case shimast.KindImportEqualsDeclaration:
-    ref := node.AsImportEqualsDeclaration().ModuleReference
-    if ref != nil && ref.Kind == shimast.KindExternalModuleReference {
-      visit(ref.AsExternalModuleReference().Expression)
+  var walk func(node *shimast.Node) bool
+  walk = func(node *shimast.Node) bool {
+    if node == nil {
+      return false
     }
-  case shimast.KindImportType:
-    arg := node.AsImportTypeNode().Argument
-    if arg != nil && arg.Kind == shimast.KindLiteralType {
-      visit(arg.AsLiteralTypeNode().Literal)
-    }
-  case shimast.KindModuleDeclaration:
-    decl := node.AsModuleDeclaration()
-    if decl != nil {
-      visit(decl.Name())
-    }
-  case shimast.KindCallExpression:
-    call := node.AsCallExpression()
-    if isModuleSpecifierCall(call) && call.Arguments != nil && len(call.Arguments.Nodes) > 0 {
-      visit(call.Arguments.Nodes[0])
+    switch node.Kind {
+    case shimast.KindImportDeclaration:
+      visit(node.AsImportDeclaration().ModuleSpecifier)
+    case shimast.KindExportDeclaration:
+      visit(node.AsExportDeclaration().ModuleSpecifier)
+    case shimast.KindImportEqualsDeclaration:
+      ref := node.AsImportEqualsDeclaration().ModuleReference
+      if ref != nil && ref.Kind == shimast.KindExternalModuleReference {
+        visit(ref.AsExternalModuleReference().Expression)
+      }
+    case shimast.KindImportType:
+      arg := node.AsImportTypeNode().Argument
+      if arg != nil && arg.Kind == shimast.KindLiteralType {
+        visit(arg.AsLiteralTypeNode().Literal)
+      }
+    case shimast.KindModuleDeclaration:
+      decl := node.AsModuleDeclaration()
+      if decl != nil {
+        visit(decl.Name())
+      }
+    case shimast.KindCallExpression:
+      call := node.AsCallExpression()
+      if isModuleSpecifierCall(call) && call.Arguments != nil && len(call.Arguments.Nodes) > 0 {
+        visit(call.Arguments.Nodes[0])
+      }
     }
-  }
-  node.ForEachChild(func(child *shimast.Node) bool {
-    visitModuleSpecifiers(child, visit)
+    node.ForEachChild(walk)
     return false
-  })
+  }
+  walk(node)
 }
 
 // isModuleSpecifierCall reports whether call is a dynamic import() or a
@@ -198,9 +207,13 @@ func (r *rewriter) rewrite(fromSource string, specifier string) (string, bool) {
   return rel, true
 }
 
-// resolveSource finds the source file that a tsconfig paths specifier resolves to.
-// It iterates over sorted patterns and, for each match, tries all substitution
-// targets (with and without known extensions) including index files.
+// resolveSource finds the source file that a tsconfig paths specifier
+// resolves to. Patterns are pre-sorted into tsc's precedence order, and like
+// tsc's tryLoadModuleUsingPaths the resolution commits to the first (best)
+// matching pattern: only that pattern's substitution targets are tried, in
+// order, with extension and index fallbacks. When none of them names a
+// program source the specifier stays unrewritten — falling through to a
+// weaker pattern would rewrite at a module the type checker never resolved.
 func (r *rewriter) resolveSource(specifier string) (string, bool) {
   for _, pattern := range r.patterns {
     star, ok := matchPattern(pattern.pattern, specifier)
@@ -214,6 +227,7 @@ func (r *rewriter) resolveSource(specifier string) (string, bool) {
         return source, true
       }
     }
+    return "", false
   }
   return "", false
 }
diff --git a/packages/paths/test/rewriter_resolve_source_commits_to_best_pattern_test.go b/packages/paths/test/rewriter_resolve_source_commits_to_best_pattern_test.go
@@ -0,0 +1,38 @@
+package paths_test
+
+import "testing"
+
+// TestRewriterResolveSourceCommitsToBestPattern verifies no fall-through past the matched pattern.
+//
+// Locks `paths.go::resolveSource` to tsc's tryLoadModuleUsingPaths contract:
+// resolution commits to the single best-precedence matching pattern and tries
+// only that pattern's substitution targets. When none of them names a program
+// source, tsc's paths lookup fails — it never consults a weaker pattern — so
+// falling through here would rewrite the import at a module the type checker
+// never resolved.
+//
+// 1. Configure a long-prefix pattern whose target is missing and a catch-all whose target exists.
+// 2. Resolve a specifier that matches both.
+// 3. Assert resolution fails instead of landing on the catch-all's source.
+func TestRewriterResolveSourceCommitsToBestPattern(t *testing.T) {
+  root := "/repo"
+  patterns := []pathsPathPattern{
+    {pattern: "*", targets: []string{"src/anywhere/*"}},
+    {pattern: "@app/*", targets: []string{"src/app/*"}},
+  }
+  pathsOrderPatterns(patterns)
+  rewriter := &pathsRewriter{
+    basePath: root,
+    patterns: patterns,
+    sourceFiles: map[string]string{
+      root + "/src/anywhere/@app/widget.ts": root + "/src/anywhere/@app/widget.ts",
+      root + "/src/anywhere/other.ts":       root + "/src/anywhere/other.ts",
+    },
+  }
+  if source, ok := pathsResolveSource(rewriter, "@app/widget"); ok {
+    t.Fatalf("resolution fell through past the best pattern to %q", source)
+  }
+  if source, ok := pathsResolveSource(rewriter, "other"); !ok || source != root+"/src/anywhere/other.ts" {
+    t.Fatalf("catch-all pattern mismatch: source=%q ok=%v", source, ok)
+  }
+}
diff --git a/website/src/content/docs/development/walkthroughs/paths.mdx b/website/src/content/docs/development/walkthroughs/paths.mdx
@@ -218,36 +218,41 @@ func visitModuleSpecifiers(node *shimast.Node, visit func(*shimast.Node)) {
   if node == nil {
     return
   }
-  switch node.Kind {
-  case shimast.KindImportDeclaration:
-    visit(node.AsImportDeclaration().ModuleSpecifier)
-  case shimast.KindExportDeclaration:
-    visit(node.AsExportDeclaration().ModuleSpecifier)
-  case shimast.KindImportEqualsDeclaration:
-    ref := node.AsImportEqualsDeclaration().ModuleReference
-    if ref != nil && ref.Kind == shimast.KindExternalModuleReference {
-      visit(ref.AsExternalModuleReference().Expression)
+  var walk func(node *shimast.Node) bool
+  walk = func(node *shimast.Node) bool {
+    if node == nil {
+      return false
     }
-  case shimast.KindImportType:
-    arg := node.AsImportTypeNode().Argument
-    if arg != nil && arg.Kind == shimast.KindLiteralType {
-      visit(arg.AsLiteralTypeNode().Literal)
-    }
-  case shimast.KindModuleDeclaration:
-    decl := node.AsModuleDeclaration()
-    if decl != nil {
-      visit(decl.Name())
-    }
-  case shimast.KindCallExpression:
-    call := node.AsCallExpression()
-    if isModuleSpecifierCall(call) && call.Arguments != nil && len(call.Arguments.Nodes) > 0 {
-      visit(call.Arguments.Nodes[0])
+    switch node.Kind {
+    case shimast.KindImportDeclaration:
+      visit(node.AsImportDeclaration().ModuleSpecifier)
+    case shimast.KindExportDeclaration:
+      visit(node.AsExportDeclaration().ModuleSpecifier)
+    case shimast.KindImportEqualsDeclaration:
+      ref := node.AsImportEqualsDeclaration().ModuleReference
+      if ref != nil && ref.Kind == shimast.KindExternalModuleReference {
+        visit(ref.AsExternalModuleReference().Expression)
+      }
+    case shimast.KindImportType:
+      arg := node.AsImportTypeNode().Argument
+      if arg != nil && arg.Kind == shimast.KindLiteralType {
+        visit(arg.AsLiteralTypeNode().Literal)
+      }
+    case shimast.KindModuleDeclaration:
+      decl := node.AsModuleDeclaration()
+      if decl != nil {
+        visit(decl.Name())
+      }
+    case shimast.KindCallExpression:
+      call := node.AsCallExpression()
+      if isModuleSpecifierCall(call) && call.Arguments != nil && len(call.Arguments.Nodes) > 0 {
+        visit(call.Arguments.Nodes[0])
+      }
     }
-  }
-  node.ForEachChild(func(child *shimast.Node) bool {
-    visitModuleSpecifiers(child, visit)
+    node.ForEachChild(walk)
     return false
-  })
+  }
+  walk(node)
 }
 
 func isModuleSpecifierCall(call *shimast.CallExpression) bool {
@@ -283,17 +288,17 @@ After the switch, `node.ForEachChild` recurses into every child. This is what ma
 The closure-based visitor is the simplest way to walk an AST in Go without an explicit interface. The shape:
 
 ```go
-func walk(node *X, visit func(*X)) {
-  if node == nil { return }
+var walk func(node *X) bool
+walk = func(node *X) bool {
+  if node == nil { return false }
   visit(node)
-  node.ForEachChild(func(child *X) bool {
-    walk(child, visit)
-    return false
-  })
+  node.ForEachChild(walk)
+  return false
 }
+walk(root)
 ```
 
-returning `false` keeps the iteration alive. Returning `true` would short-circuit, useful for "find the first node matching predicate," not useful when you want to visit every node.
+returning `false` keeps the iteration alive. Returning `true` would short-circuit, useful for "find the first node matching predicate," not useful when you want to visit every node. Declare the recursion closure once per walk and hand the same value to every `ForEachChild` call — building a fresh closure at each node allocates once per AST node, which a program-wide pass pays millions of times.
 
 ### 4. Resolving a specifier
 
@@ -348,6 +353,7 @@ func (r *rewriter) resolveSource(specifier string) (string, bool) {
         return source, true
       }
     }
+    return "", false
   }
   return "", false
 }
@@ -377,6 +383,8 @@ For pattern `@lib/*` and specifier `@lib/greet`:
 
 The two guards mirror tsc: a pattern with more than one `*` is not a pattern at all (`TryParsePattern` discards it), and a specifier shorter than the literal halves combined must not match — it can still satisfy both the prefix and suffix probes (`"@lib/x"` against `"@lib/x*x"`), and slicing the star capture out of it would panic on inverted bounds.
 
+Resolution also _commits_ to the first (best-precedence) matching pattern, exactly like tsc's `tryLoadModuleUsingPaths`: only that pattern's targets are tried, and when none of them names a program source the specifier stays unrewritten. Falling through to a weaker pattern would rewrite the import at a module the type checker never resolved.
+
 The captured `*` substitutes into each target: `./src/modules/*` → `./src/modules/greet`. The candidate is then joined against `basePath` (the tsconfig directory) and looked up in `r.sourceFiles`.
 
 `lookupSource` walks three stages, falling through on each miss: literal match in the `sourceFiles` map → stem with each of `.ts` / `.tsx` / `.mts` / `.cts` / `.js` / `.jsx` / `.mjs` / `.cjs` appended → stem + `/index.<ext>` for directory-style imports. The exact source is in [`driver/paths.go::lookupSource`](https://github.com/samchon/ttsc/tree/master/packages/paths/driver/paths.go).
