@ttsc/banner 0.26.0 → 0.26.2

package/driver/banner.go

@@ -92,16 +92,26 @@ func parseBanner(config map[string]any, cwd, tsconfigPath string) (string, error
   return b.String(), nil
 }
 
+// sanitizeJSDocLine escapes any JSDoc-closing sequence in a banner text line
+// by replacing "*/" with "* /" so the generated block comment stays valid.
+func sanitizeJSDocLine(line string) string {
+  return strings.ReplaceAll(line, "*/", "* /")
+}
+
 // resolveBannerText extracts the banner text from the plugin config.
 // The config entry is validated first: only the "configFile" key (plus
 // framework keys) is accepted. When "configFile" is present its value is
 // resolved to an absolute path and loaded. When absent the upward-walk
 // discovery is used. Returns an error when the config is invalid or when
 // no banner text can be found.
+//
+// The discovery base directory doubles as the resolution root the config
+// loader anchors its toolchain lookup on; see configToolAnchors.
 func resolveBannerText(config map[string]any, cwd, tsconfigPath string) (string, error) {
   if err := validateBannerConfig(config); err != nil {
     return "", err
   }
+  resolutionRoot := tsconfigBaseDir(cwd, tsconfigPath)
 
   if rawConfigFile, ok := config["configFile"]; ok {
     configFile, ok := rawConfigFile.(string)
@@ -109,7 +119,7 @@ func resolveBannerText(config map[string]any, cwd, tsconfigPath string) (string,
       return "", fmt.Errorf("@ttsc/banner: \"configFile\" must be a non-empty string path")
     }
     location := resolveBannerConfigPath(configFile, cwd, tsconfigPath)
-    raw, err := loadBannerConfigFile(location)
+    raw, err := loadBannerConfigFile(location, resolutionRoot)
     if err != nil {
       return "", err
     }
@@ -130,7 +140,7 @@ func resolveBannerText(config map[string]any, cwd, tsconfigPath string) (string,
   if location == "" {
     return "", fmt.Errorf("@ttsc/banner: no banner.config.{ts,cts,mts,js,cjs,mjs,json} file found; create one or set \"configFile\" in the tsconfig plugin entry")
   }
-  raw, err := loadBannerConfigFile(location)
+  raw, err := loadBannerConfigFile(location, resolutionRoot)
   if err != nil {
     return "", err
   }
@@ -238,7 +248,11 @@ func tsconfigBaseDir(cwd, tsconfigPath string) string {
 // must be named banner.config.{ts,cts,mts,js,cjs,mjs,json}; JS/CJS/MJS variants
 // run under Node, TypeScript variants compile and run via ttsx in a temp
 // directory, and JSON files are parsed natively.
-func loadBannerConfigFile(location string) (any, error) {
+//
+// resolutionRoot is the project directory the TypeScript branch anchors its
+// toolchain resolution on when the config file's own ancestry answers nothing;
+// see configToolAnchors. The JSON and JS branches spawn no ttsx and ignore it.
+func loadBannerConfigFile(location, resolutionRoot string) (any, error) {
   if !isBannerConfigFileName(filepath.Base(location)) {
     return nil, fmt.Errorf("@ttsc/banner: config file must be named banner.config.{ts,cts,mts,js,cjs,mjs,json}: %s", location)
   }
@@ -249,7 +263,7 @@ func loadBannerConfigFile(location string) (any, error) {
   case ".js", ".cjs", ".mjs":
     return loadBannerScriptConfigFile(location)
   }
-  return loadBannerTypeScriptConfigFile(location)
+  return loadBannerTypeScriptConfigFile(location, resolutionRoot)
 }
 
 // isBannerConfigFileName reports whether name is an allowed banner config file name.
@@ -362,7 +376,11 @@ function toSerializableBanner(value) {
 // is created so the config file can import its own dependencies. The ttsx
 // build runs with `--no-plugins` so evaluating the config never triggers the
 // host project's transform/check plugins against the loader tsconfig.
-func loadBannerTypeScriptConfigFile(location string) (any, error) {
+//
+// Both tools this spawns — the launcher and the compiler handed to it — are
+// resolved from the project rather than from the process environment alone;
+// see configToolAnchors.
+func loadBannerTypeScriptConfigFile(location, resolutionRoot string) (any, error) {
   tempDir, err := os.MkdirTemp(loaderTempBase(location, os.TempDir()), "ttsc-banner-config-")
   if err != nil {
     return nil, fmt.Errorf("@ttsc/banner: create config loader tempdir: %w", err)
@@ -393,14 +411,15 @@ func loadBannerTypeScriptConfigFile(location string) (any, error) {
     "--cache-dir", filepath.Join(tempDir, "cache"),
     "--no-plugins",
   }
-  if tsgo := os.Getenv("TTSC_TSGO_BINARY"); tsgo != "" {
+  anchors := configToolAnchors(location, resolutionRoot)
+  if tsgo := resolveConfigTsgo(anchors); tsgo != "" {
     args = append(args, "--binary", tsgo)
   }
   args = append(args, loader)
 
   ctx, cancel := context.WithCancel(context.Background())
   defer cancel()
-  cmd := ttsxCommandContext(ctx, args...)
+  cmd := ttsxCommandContext(ctx, anchors, args...)
   cmd.Env = nodeConfigLoaderEnv(location)
   // The child's stderr is human output and goes straight to this process's
   // stderr as it is written. Collecting it only to replay it afterwards is what
@@ -424,20 +443,6 @@ func loadBannerTypeScriptConfigFile(location string) (any, error) {
   return out, nil
 }
 
-// relativeImportSpecifier returns a "./" or "../"-prefixed slash-separated
-// import specifier for location relative to fromDir.
-func relativeImportSpecifier(fromDir, location string) (string, error) {
-  relative, err := filepath.Rel(fromDir, location)
-  if err != nil {
-    return "", fmt.Errorf("@ttsc/banner: resolve relative config import %s: %w", location, err)
-  }
-  relative = filepath.ToSlash(relative)
-  if strings.HasPrefix(relative, "../") || strings.HasPrefix(relative, "./") {
-    return relative, nil
-  }
-  return "./" + relative, nil
-}
-
 // bannerTypeScriptConfigLoaderSource returns the source of a TypeScript loader
 // module that imports the banner config file specified by importLiteral (a
 // JSON-encoded import specifier) and writes the serialized banner value to stdout.
@@ -551,6 +556,23 @@ func typeScriptConfigLoaderTsconfig(loader, location, outDir string) string {
   return string(body)
 }
 
+// ttsc:config-loader-shared begin
+//
+// One policy in three Go copies: everything between these markers is
+// duplicated verbatim in packages/lint/linthost/config.go,
+// packages/banner/driver/banner.go and packages/strip/driver/config.go. #1169
+// decided against extracting it — the only home the three modules could share
+// is the public `packages/ttsc/driver` seam, and packages/lint's go.mod
+// deliberately requires no in-tree ttsc module — and replaced the checklist
+// with a gate: `scripts/ci/config-loader-copies.cjs` compares every function
+// between these markers across all three copies on every pull request, so
+// editing one and not the others fails by name. That file's header carries the
+// full decision and the rules for changing this block.
+//
+// The code between the markers must stay identical. Comments may differ, the
+// `@ttsc/<pkg>:` error prefix may differ, and @ttsc/strip spells each name with
+// a `strip` prefix. Anything package-specific belongs outside the markers.
+
 // configModuleOption returns the loader tsconfig's "module" for a config file:
 // the module kind Node itself would give that file.
 //
@@ -673,21 +695,240 @@ func resolveDirLink(dir string) string {
   return dir
 }
 
+// realpathIfPossible resolves location through its symlinks, and returns it
+// unchanged when it cannot be evaluated (a path that does not exist, or an
+// NTFS junction filepath.EvalSymlinks refuses to traverse).
+func realpathIfPossible(location string) string {
+  real, err := filepath.EvalSymlinks(location)
+  if err != nil {
+    return location
+  }
+  return real
+}
+
+// Both tools the TypeScript config evaluator needs — the `ttsx` launcher it
+// spawns and the native compiler it hands that launcher — are resolved from
+// the project being compiled, with an explicit environment variable winning
+// and a last resort that invents no path.
+//
+// The three Go copies are held identical by the gate named at the top of this
+// block. The JS original — `resolveConfigTsgo` / `resolveTtsxLauncher` in
+// packages/lint/src/index.ts — is a fourth copy in another language that no Go
+// gate can reach; what it owes is that both policies stay describable in one
+// sentence.
+//
+// The environment alone is the wrong place to ask. `ttsx` exports
+// TTSC_TSGO_BINARY and TTSC_TTSX_BINARY to its own descendants, so a host
+// launched under `ttsx` inherited both and a host launched any other way
+// inherited neither. The shipped `ttscserver` binary invoked with its
+// documented `--tsgo <path>` flag keeps that path in a local and exports
+// nothing, and an embedder of the driver package exports nothing either. For
+// those the evaluator spawned a bare `ttsx` that only a global install puts on
+// PATH, and, past that, a compiler-less child that aborted with
+// `ttsc: typescript is required` before a line of the config was read.
+//
+// configToolAnchors lists the file paths those resolutions walk upward from,
+// in order: the config file being evaluated, then the resolution root's
+// manifest. The config comes first because it is the file whose own
+// installation decides which toolchain the config's imports were written
+// against; the resolution root answers for a config that lives outside the
+// project tree (a `configFile` pointed at a shared package), and for one
+// discovered above a workspace that installs its own toolchain.
+func configToolAnchors(configPath, resolutionRoot string) []string {
+  anchors := make([]string, 0, 2)
+  if strings.TrimSpace(configPath) != "" {
+    anchors = append(anchors, configPath)
+  }
+  if strings.TrimSpace(resolutionRoot) != "" {
+    anchors = append(anchors, filepath.Join(resolutionRoot, "package.json"))
+  }
+  return anchors
+}
+
+// resolveConfigTsgo returns the native TypeScript compiler the evaluator hands
+// its ttsx child through `--binary`, or "" to leave the child resolving for
+// itself.
+//
+// The child runs with `--cwd <ephemeral loader dir>`, so it cannot discover
+// `typescript` the way an ordinary invocation does: linkNearestNodeModules is
+// the only thing that puts the project's modules within its reach, and it links
+// nothing when the config's ancestry carries no node_modules. An explicit
+// TTSC_TSGO_BINARY still wins, so an embedder that pins a compiler keeps
+// pinning it. "" is the unchanged last resort: a project that cannot answer
+// here could not answer inside the child either, and the child's own diagnostic
+// is the one that names the missing package.
+func resolveConfigTsgo(anchors []string) string {
+  if explicit := strings.TrimSpace(os.Getenv("TTSC_TSGO_BINARY")); explicit != "" {
+    return explicit
+  }
+  for _, anchor := range anchors {
+    if binary := tsgoBinaryFrom(anchor); binary != "" {
+      return binary
+    }
+  }
+  return ""
+}
+
+// tsgoBinaryFrom returns the platform compiler executable of the `typescript`
+// install `anchor` can see, or "" when this anchor reaches neither the package
+// nor its platform dependency.
+//
+// Mirrors resolveTsgo.ts so the Go plugin and the JS launcher name one file:
+// the `typescript` manifest, then `@typescript/typescript-<platform>-<arch>`
+// resolved from that manifest, then `lib/tsc` inside it.
+//
+// The install is chased to its real directory before the second hop, because
+// Node resolves a module's own dependencies from its real location. pnpm keeps
+// the real `typescript` directory in its content-addressed store with the
+// platform package beside it and leaves a link in the project's node_modules,
+// so a walk that started at the link would climb straight past the platform
+// package. NTFS junctions defeat filepath.EvalSymlinks, so the link component
+// is chased by hand first, the same order loaderTempBase uses.
+func tsgoBinaryFrom(anchor string) string {
+  manifest := nodePackageManifestFrom(anchor, "typescript")
+  if manifest == "" {
+    return ""
+  }
+  packageDir := realpathIfPossible(resolveDirLink(filepath.Dir(manifest)))
+  platform, arch := nodePlatformPair()
+  platformManifest := nodePackageManifestFrom(
+    filepath.Join(packageDir, "package.json"),
+    "@typescript/typescript-"+platform+"-"+arch,
+  )
+  if platformManifest == "" {
+    return ""
+  }
+  name := "tsc"
+  if runtime.GOOS == "windows" {
+    name = "tsc.exe"
+  }
+  binary := filepath.Join(filepath.Dir(platformManifest), "lib", name)
+  if stat, err := os.Stat(binary); err != nil || stat.IsDir() {
+    return ""
+  }
+  return binary
+}
+
+// resolveTtsxLauncher returns the launcher ttsxCommandContext spawns.
+//
+// An explicit TTSC_TTSX_BINARY wins. Otherwise the launcher is derived from the
+// `ttsc` installation one of the anchors can see, because a bare command name
+// only works when a bin link happens to be on PATH — which it is for a global
+// install and is not for the ordinary project-local one. The bare `"ttsx"` name
+// remains the unchanged last resort for an installation no anchor reaches.
+func resolveTtsxLauncher(anchors []string) string {
+  if explicit := strings.TrimSpace(os.Getenv("TTSC_TTSX_BINARY")); explicit != "" {
+    return explicit
+  }
+  for _, anchor := range anchors {
+    if launcher := ttsxLauncherFrom(anchor); launcher != "" {
+      return launcher
+    }
+  }
+  return "ttsx"
+}
+
+// ttsxLauncherFrom returns `lib/launcher/ttsx.js` of the `ttsc` install
+// `anchor` can see, or "" when this anchor reaches no such install. Only the
+// manifest is an exported subpath, so the launcher is derived from where the
+// manifest resolved rather than requested as a subpath of its own.
+func ttsxLauncherFrom(anchor string) string {
+  manifest := nodePackageManifestFrom(anchor, "ttsc")
+  if manifest == "" {
+    return ""
+  }
+  launcher := filepath.Join(filepath.Dir(manifest), "lib", "launcher", "ttsx.js")
+  if stat, err := os.Stat(launcher); err != nil || stat.IsDir() {
+    return ""
+  }
+  return launcher
+}
+
+// nodePackageManifestFrom resolves `<pkg>/package.json` the way Node's
+// require.resolve does from the FILE `anchor`: walk upward from the anchor's
+// directory and return the first `<dir>/node_modules/<pkg>/package.json` that
+// exists. The anchor is treated as a file path, so its own directory is the
+// first candidate's parent, and it need not exist — Node derives the search
+// paths from the string alone.
+//
+// A directory already named `node_modules` contributes no candidate of its own,
+// matching Module._nodeModulePaths, so nothing ever resolves through
+// `node_modules/node_modules`.
+//
+// A relative anchor is resolved against the process directory before the walk,
+// again matching Node. Walking a relative path instead would terminate at "."
+// after one step and silently answer nothing for a config named relatively.
+func nodePackageManifestFrom(anchor, pkg string) string {
+  if strings.TrimSpace(anchor) == "" || pkg == "" {
+    return ""
+  }
+  if absolute, err := filepath.Abs(anchor); err == nil {
+    anchor = absolute
+  }
+  dir := filepath.Dir(filepath.Clean(anchor))
+  for {
+    if filepath.Base(dir) != "node_modules" {
+      candidate := filepath.Join(dir, "node_modules", filepath.FromSlash(pkg), "package.json")
+      if stat, err := os.Stat(candidate); err == nil && !stat.IsDir() {
+        return candidate
+      }
+    }
+    parent := filepath.Dir(dir)
+    if parent == dir {
+      return ""
+    }
+    dir = parent
+  }
+}
+
+// nodePlatformPair is nodePlatformPairFor applied to this build's own target.
+func nodePlatformPair() (string, string) {
+  return nodePlatformPairFor(runtime.GOOS, runtime.GOARCH)
+}
+
+// nodePlatformPairFor maps a Go build target onto the `process.platform` and
+// `process.arch` pair npm spells a platform package with, so the package name
+// this plugin resolves is the same one the JS launcher resolves.
+//
+// Only the members whose two vocabularies disagree are mapped. Every other
+// value is identical on both sides and passes through, which keeps a target
+// neither side publishes yet resolvable rather than silently wrong, and keeps
+// this from becoming a list that has to grow with every new port.
+func nodePlatformPairFor(goos, goarch string) (string, string) {
+  platform := goos
+  switch platform {
+  case "windows":
+    platform = "win32"
+  case "solaris":
+    platform = "sunos"
+  }
+  arch := goarch
+  switch arch {
+  case "amd64":
+    arch = "x64"
+  case "386":
+    arch = "ia32"
+  case "ppc64le":
+    arch = "ppc64"
+  }
+  return platform, arch
+}
+
 // ttsxCommand builds an exec.Cmd that runs ttsx with the given args.
-// When TTSC_TTSX_BINARY has a script extension (.js, .ts, …) the binary is
+// When the resolved launcher has a script extension (.js, .ts, …) the binary is
 // invoked via the Node runtime so it is executed correctly on all platforms.
-func ttsxCommand(args ...string) *exec.Cmd {
-  return ttsxCommandContext(context.Background(), args...)
+func ttsxCommand(anchors []string, args ...string) *exec.Cmd {
+  return ttsxCommandContext(context.Background(), anchors, args...)
 }
 
 // ttsxCommandContext is the context-bound variant used by config loaders. It
 // carries no deadline: evaluating a user config is the user's own code running,
 // and how long that is allowed to take is not this binary's decision.
-func ttsxCommandContext(ctx context.Context, args ...string) *exec.Cmd {
-  ttsx := os.Getenv("TTSC_TTSX_BINARY")
-  if ttsx == "" {
-    ttsx = "ttsx"
-  }
+//
+// `anchors` are the file paths the launcher is resolved from; see
+// resolveTtsxLauncher.
+func ttsxCommandContext(ctx context.Context, anchors []string, args ...string) *exec.Cmd {
+  ttsx := resolveTtsxLauncher(anchors)
   if shouldRunTtsxThroughNode(ttsx) {
     node := os.Getenv("TTSC_NODE_BINARY")
     if node == "" {
@@ -771,6 +1012,20 @@ func findNearestNodeModules(start string) string {
   }
 }
 
+// relativeImportSpecifier returns a "./" or "../"-prefixed slash-separated
+// import specifier for location relative to fromDir.
+func relativeImportSpecifier(fromDir, location string) (string, error) {
+  relative, err := filepath.Rel(fromDir, location)
+  if err != nil {
+    return "", fmt.Errorf("@ttsc/banner: resolve relative config import %s: %w", location, err)
+  }
+  relative = filepath.ToSlash(relative)
+  if strings.HasPrefix(relative, "../") || strings.HasPrefix(relative, "./") {
+    return relative, nil
+  }
+  return "./" + relative, nil
+}
+
 // setEnv returns a copy of env with key=value. If key already exists in env,
 // its value is updated in-place; otherwise the entry is appended.
 func setEnv(env []string, key, value string) []string {
@@ -784,12 +1039,6 @@ func setEnv(env []string, key, value string) []string {
   return append(env, prefix+value)
 }
 
-// sanitizeJSDocLine escapes any JSDoc-closing sequence in a banner text line
-// by replacing "*/" with "* /" so the generated block comment stays valid.
-func sanitizeJSDocLine(line string) string {
-  return strings.ReplaceAll(line, "*/", "* /")
-}
-
 // loaderFailureReason reads the failure envelope a config loader writes to its
 // payload channel when it stops on an error it can name.
 //
@@ -809,3 +1058,5 @@ func loaderFailureReason(output []byte) string {
   }
   return strings.TrimSpace(envelope.Message)
 }
+
+// ttsc:config-loader-shared end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/banner",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "First-party ttsc plugin that adds package-documentation JSDoc banners during emit.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -35,7 +35,7 @@
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
     "typescript": "^7.0.2",
-    "ttsc": "0.26.0"
+    "ttsc": "0.26.2"
   },
   "repository": {
     "type": "git",