@ttsc/banner 0.26.1 → 0.27.0

package/driver/banner.go

@@ -3,6 +3,7 @@ package banner
 import (
   "bytes"
   "context"
+  "crypto/sha256"
   "encoding/json"
   "fmt"
   "os"
@@ -61,13 +62,21 @@ func validateBannerConfig(config map[string]any) error {
 // SourcePreamble resolves the banner text from the plugin config and returns it
 // formatted as a JSDoc block comment suitable for prepending to each emitted file.
 func (plugin) SourcePreamble(ctx driver.PluginContext) (string, error) {
-  return parseBanner(ctx.Entry.Config, ctx.Cwd, ctx.Tsconfig)
+  return parseBannerWithReporters(ctx.Entry.Config, ctx.Cwd, ctx.Tsconfig, ctx.ReportHostInput, ctx.ReportHostInputHash, ctx.ReportHostInputRealpath)
 }
 
 // parseBanner resolves and formats banner text into a JSDoc block comment.
 // Trailing blank lines are stripped from the resolved text before formatting.
 func parseBanner(config map[string]any, cwd, tsconfigPath string) (string, error) {
-  text, err := resolveBannerText(config, cwd, tsconfigPath)
+  return parseBannerWithReporter(config, cwd, tsconfigPath, nil)
+}
+
+func parseBannerWithReporter(config map[string]any, cwd, tsconfigPath string, reporter func(string)) (string, error) {
+  return parseBannerWithReporters(config, cwd, tsconfigPath, reporter, nil, nil)
+}
+
+func parseBannerWithReporters(config map[string]any, cwd, tsconfigPath string, reporter func(string), hashReporter func(string, *string), realpathReporter func(string, *string)) (string, error) {
+  text, err := resolveBannerTextWithReporters(config, cwd, tsconfigPath, reporter, hashReporter, realpathReporter)
   if err != nil {
     return "", err
   }
@@ -92,16 +101,34 @@ 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) {
+  return resolveBannerTextWithReporter(config, cwd, tsconfigPath, nil)
+}
+
+func resolveBannerTextWithReporter(config map[string]any, cwd, tsconfigPath string, reporter func(string)) (string, error) {
+  return resolveBannerTextWithReporters(config, cwd, tsconfigPath, reporter, nil, nil)
+}
+
+func resolveBannerTextWithReporters(config map[string]any, cwd, tsconfigPath string, reporter func(string), hashReporter func(string, *string), realpathReporter func(string, *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,11 +136,12 @@ 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)
+    loaded, err := loadBannerConfigFileWithInputs(location, resolutionRoot)
     if err != nil {
       return "", err
     }
-    text, ok, err := bannerTextFromConfigValue(raw, filepath.Base(location))
+    reportBannerConfigInputs(loaded.inputs, loaded.hashes, loaded.realpaths, reporter, hashReporter, realpathReporter)
+    text, ok, err := bannerTextFromConfigValue(loaded.value, filepath.Base(location))
     if err != nil {
       return "", err
     }
@@ -130,11 +158,12 @@ 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)
+  loaded, err := loadBannerConfigFileWithInputs(location, resolutionRoot)
   if err != nil {
     return "", err
   }
-  text, ok, err := bannerTextFromConfigValue(raw, filepath.Base(location))
+  reportBannerConfigInputs(loaded.inputs, loaded.hashes, loaded.realpaths, reporter, hashReporter, realpathReporter)
+  text, ok, err := bannerTextFromConfigValue(loaded.value, filepath.Base(location))
   if err != nil {
     return "", err
   }
@@ -238,18 +267,123 @@ 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) {
+  loaded, err := loadBannerConfigFileWithInputs(location, resolutionRoot)
+  return loaded.value, err
+}
+
+type bannerLoadedConfig struct {
+  hashes    map[string]*string
+  inputs    []string
+  realpaths map[string]*string
+  value     any
+}
+
+func loadBannerConfigFileWithInputs(location, resolutionRoot string) (bannerLoadedConfig, 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)
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: config file must be named banner.config.{ts,cts,mts,js,cjs,mjs,json}: %s", location)
   }
   ext := strings.ToLower(filepath.Ext(location))
   switch ext {
   case ".json":
-    return loadBannerJSONConfigFile(location)
+    body, err := os.ReadFile(location)
+    if err != nil {
+      return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: read config file %s: %w", location, err)
+    }
+    value, err := parseBannerJSONConfigFile(location, body)
+    digest := fmt.Sprintf("%x", sha256.Sum256(body))
+    return bannerLoadedConfig{hashes: map[string]*string{location: &digest}, inputs: []string{location}, realpaths: map[string]*string{location: physicalHostInput(location)}, value: value}, err
   case ".js", ".cjs", ".mjs":
-    return loadBannerScriptConfigFile(location)
+    return loadBannerScriptConfigFileWithInputs(location)
+  }
+  return loadBannerTypeScriptConfigFileWithInputs(location, resolutionRoot)
+}
+
+func reportBannerConfigInputs(inputs []string, hashes, realpaths map[string]*string, reporter func(string), hashReporter, realpathReporter func(string, *string)) {
+  if reporter == nil && hashReporter == nil && realpathReporter == nil {
+    return
+  }
+  for _, input := range inputs {
+    if reporter != nil {
+      reporter(input)
+    }
+    if hashReporter != nil {
+      if hash, ok := hashes[input]; ok {
+        hashReporter(input, hash)
+      }
+    }
+    if realpathReporter != nil {
+      if realpath, ok := realpaths[input]; ok {
+        realpathReporter(input, realpath)
+      }
+    }
+  }
+}
+
+func physicalHostInput(file string) *string {
+  resolved, err := filepath.Abs(file)
+  if err != nil {
+    return nil
+  }
+  resolved = filepath.Clean(resolved)
+  seen := make(map[string]struct{})
+  for range 255 {
+    if _, exists := seen[resolved]; exists {
+      return nil
+    }
+    seen[resolved] = struct{}{}
+    if evaluated, evalErr := filepath.EvalSymlinks(resolved); evalErr == nil {
+      evaluated, evalErr = filepath.Abs(evaluated)
+      if evalErr != nil {
+        return nil
+      }
+      evaluated = filepath.Clean(evaluated)
+      if _, statErr := os.Stat(evaluated); statErr != nil {
+        return nil
+      }
+      return &evaluated
+    }
+    next, ok := resolveHostInputLinkAncestor(resolved)
+    if !ok {
+      return nil
+    }
+    resolved = next
+  }
+  return nil
+}
+
+// resolveHostInputLinkAncestor follows the nearest link-like ancestor and
+// reattaches its remaining suffix. Windows junction children can be opened and
+// os.Readlink exposes the junction itself even when EvalSymlinks rejects the
+// complete child path.
+func resolveHostInputLinkAncestor(location string) (string, bool) {
+  probe := filepath.Clean(location)
+  suffix := make([]string, 0)
+  for {
+    if target, err := os.Readlink(probe); err == nil {
+      if !filepath.IsAbs(target) {
+        target = filepath.Join(filepath.Dir(probe), target)
+      }
+      for i := len(suffix) - 1; i >= 0; i-- {
+        target = filepath.Join(target, suffix[i])
+      }
+      absolute, absErr := filepath.Abs(target)
+      if absErr != nil {
+        return "", false
+      }
+      return filepath.Clean(absolute), true
+    }
+    parent := filepath.Dir(probe)
+    if parent == probe {
+      return "", false
+    }
+    suffix = append(suffix, filepath.Base(probe))
+    probe = parent
   }
-  return loadBannerTypeScriptConfigFile(location)
 }
 
 // isBannerConfigFileName reports whether name is an allowed banner config file name.
@@ -276,6 +410,10 @@ func loadBannerJSONConfigFile(location string) (any, error) {
   if err != nil {
     return nil, fmt.Errorf("@ttsc/banner: read config file %s: %w", location, err)
   }
+  return parseBannerJSONConfigFile(location, body)
+}
+
+func parseBannerJSONConfigFile(location string, body []byte) (any, error) {
   // Strip a leading UTF-8 BOM so files saved by Windows editors round
   // trip through json.Unmarshal without an opaque "invalid character" failure.
   body = bytes.TrimPrefix(body, []byte{0xEF, 0xBB, 0xBF})
@@ -290,8 +428,207 @@ func loadBannerJSONConfigFile(location string) (any, error) {
 // running a small Node.js loader script that dynamic-imports the file and
 // serializes its exported value to stdout as JSON.
 func loadBannerScriptConfigFile(location string) (any, error) {
+  loaded, err := loadBannerScriptConfigFileWithInputs(location)
+  return loaded.value, err
+}
+
+func loadBannerScriptConfigFileWithInputs(location string) (bannerLoadedConfig, error) {
   const script = `
-const { pathToFileURL } = require("node:url");
+const { createRequire, isBuiltin, registerHooks } = require("node:module");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { fileURLToPath, pathToFileURL } = require("node:url");
+const inputs = new Set();
+const hashes = new Map();
+const realpaths = new Map();
+const signatures = new Map();
+const unstableHashes = new Set();
+
+function existingFile(file) {
+  try { return fs.statSync(file).isFile(); }
+  catch { return false; }
+}
+
+function missingPathError(error) {
+  return error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
+
+function inputMetadataSignature(file) {
+  const requested = path.resolve(file);
+  let current = requested;
+  for (;;) {
+    try {
+      const link = fs.lstatSync(current, { bigint: true });
+      let target = link;
+      if (link.isSymbolicLink()) {
+        try { target = fs.statSync(current, { bigint: true }); }
+        catch { return undefined; }
+      }
+      return [path.relative(current, requested), link.dev, link.ino, link.mode, link.size, link.mtimeNs, link.ctimeNs, target.dev, target.ino, target.mode, target.size, target.mtimeNs, target.ctimeNs].join(":");
+    } catch (error) {
+      if (!missingPathError(error)) return undefined;
+      const parent = path.dirname(current);
+      if (parent === current) return undefined;
+      current = parent;
+    }
+  }
+}
+
+function recordInput(file) {
+  file = path.resolve(file);
+  inputs.add(file);
+  if (unstableHashes.has(file)) return;
+  const beforeSignature = inputMetadataSignature(file);
+  let observed;
+  let observedRealpath;
+  try { observed = fs.statSync(file).isDirectory() ? crypto.createHash("sha256").update("ttsc:host-input:directory\\0").digest("hex") : crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+  catch { observed = null; }
+  try { observedRealpath = fs.realpathSync.native(file); }
+  catch { observedRealpath = null; }
+  const afterSignature = inputMetadataSignature(file);
+  if (beforeSignature === undefined || afterSignature === undefined || beforeSignature !== afterSignature || (signatures.has(file) && signatures.get(file) !== afterSignature) || (hashes.has(file) && hashes.get(file) !== observed) || (realpaths.has(file) && realpaths.get(file) !== observedRealpath)) {
+    hashes.delete(file);
+    realpaths.delete(file);
+    signatures.delete(file);
+    unstableHashes.add(file);
+    return;
+  }
+  signatures.set(file, afterSignature);
+  hashes.set(file, observed);
+  realpaths.set(file, observedRealpath);
+}
+
+function recordFile(file) {
+  const resolvedFile = path.resolve(file);
+  recordInput(resolvedFile);
+  for (let directory = path.dirname(resolvedFile);;) {
+    const manifest = path.join(directory, "package.json");
+    recordInput(manifest);
+    if (existingFile(manifest)) {
+      break;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      break;
+    }
+    directory = parent;
+  }
+}
+
+function recordPackageManifests(file) {
+  for (let directory = path.dirname(path.resolve(file));;) {
+    const manifest = path.join(directory, "package.json");
+    recordInput(manifest);
+    if (existingFile(manifest)) return;
+    const parent = path.dirname(directory);
+    if (parent === directory) return;
+    directory = parent;
+  }
+}
+
+const moduleProbeExtensions = [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json", ".node"];
+function moduleCandidates(base) {
+  return [
+    base,
+    ...moduleProbeExtensions.map((extension) => base + extension),
+    path.join(base, "package.json"),
+    ...moduleProbeExtensions.map((extension) => path.join(base, "index" + extension)),
+  ];
+}
+const recordedModuleBases = new Set();
+function recordManifestTargets(value, directory, allowBare = false) {
+  if (typeof value === "string") {
+    if (value !== "" && (allowBare || value.startsWith("./") || value.startsWith("../"))) recordModuleCandidates(path.resolve(directory, value));
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) recordManifestTargets(item, directory, allowBare);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) recordManifestTargets(item, directory, allowBare);
+  }
+}
+function recordModuleCandidates(base) {
+  const resolvedBase = path.resolve(base);
+  if (recordedModuleBases.has(resolvedBase)) return;
+  recordedModuleBases.add(resolvedBase);
+  for (const candidate of moduleCandidates(resolvedBase)) recordInput(candidate);
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(resolvedBase, "package.json"), "utf8").replace(/^\uFEFF/, ""));
+    recordManifestTargets(manifest.exports, resolvedBase);
+    recordManifestTargets(manifest.module, resolvedBase, true);
+    recordManifestTargets(manifest.main, resolvedBase, true);
+  } catch {}
+}
+function candidateSelected(base, resolvedFile) {
+  for (const candidate of moduleCandidates(base)) {
+    try {
+      const canonical = fs.realpathSync.native(candidate);
+      const relative = path.relative(canonical, resolvedFile);
+      if (relative === "" || (fs.statSync(canonical).isDirectory() && relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative))) return true;
+    } catch {}
+  }
+  return false;
+}
+function localBases(specifier, parentDirectory) {
+  if (specifier.startsWith("file:")) return [fileURLToPath(specifier)];
+  const raw = path.resolve(parentDirectory, specifier);
+  const suffixStart = specifier.search(/[?#]/);
+  if (suffixStart === -1) return [raw];
+  const pathname = specifier.slice(0, suffixStart);
+  return pathname === "" ? [raw] : [...new Set([raw, path.resolve(parentDirectory, pathname)])];
+}
+function recordResolutionCandidates(specifier, parentURL, resolvedURL) {
+  if (typeof parentURL !== "string" || !parentURL.startsWith("file:")) return;
+  const parentDirectory = path.dirname(fileURLToPath(parentURL));
+  let resolvedFile;
+  try {
+    resolvedFile = typeof resolvedURL === "string" && resolvedURL.startsWith("file:")
+      ? fs.realpathSync.native(fileURLToPath(resolvedURL))
+      : undefined;
+  } catch {}
+  if (specifier.startsWith(".") || path.isAbsolute(specifier) || specifier.startsWith("file:")) {
+    try {
+      for (const base of localBases(specifier, parentDirectory)) {
+        recordPackageManifests(base);
+        let exact = false;
+        try { exact = resolvedFile === undefined ? fs.statSync(base).isFile() : fs.realpathSync.native(base) === resolvedFile; } catch {}
+        if (exact) recordInput(base);
+        else recordModuleCandidates(base);
+      }
+    } catch {}
+    return;
+  }
+  if (isBuiltin(specifier) || specifier.startsWith("#")) return;
+  const parts = specifier.split("/");
+  const packageParts = parts[0].startsWith("@") ? parts.slice(0, 2) : parts.slice(0, 1);
+  if (packageParts.some((part) => part === undefined || part === "")) return;
+  const packageName = packageParts.join("/");
+  const subpath = parts.slice(packageParts.length);
+  const searchPaths = createRequire(parentURL).resolve.paths(specifier) ?? [];
+  for (const searchPath of searchPaths) {
+    const packageDirectory = path.join(searchPath, packageName);
+    recordModuleCandidates(packageDirectory);
+    if (subpath.length !== 0) recordModuleCandidates(path.join(packageDirectory, ...subpath));
+    if (resolvedFile !== undefined && candidateSelected(packageDirectory, resolvedFile)) break;
+  }
+}
+
+recordFile(process.argv[1]);
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    recordResolutionCandidates(specifier, context.parentURL, undefined);
+    const resolved = nextResolve(specifier, context);
+    const url = typeof resolved === "string" ? resolved : resolved && resolved.url;
+    recordResolutionCandidates(specifier, context.parentURL, url);
+    if (typeof url === "string" && url.startsWith("file:")) {
+      recordFile(fileURLToPath(url));
+    }
+    return resolved;
+  },
+});
 
 (async () => {
   const mod = await import(pathToFileURL(process.argv[1]).href);
@@ -307,15 +644,11 @@ const { pathToFileURL } = require("node:url");
     break;
   }
   const value = typeof current === "function" ? await current() : current;
-  process.stdout.write(JSON.stringify(toSerializableBanner(value)));
+  const serializedValue = toSerializableBanner(value);
+  for (const input of [...inputs]) recordInput(input);
+  process.stdout.write(JSON.stringify({ value: serializedValue, hashes: Object.fromEntries(hashes), inputs: [...inputs].sort(), realpaths: Object.fromEntries(realpaths) }));
 })().catch((error) => {
   process.stderr.write(error && error.stack ? error.stack : String(error));
-  // The stack above is for the reader. This is for the caller: the parent reads
-  // stdout as the payload channel either way, so a failure reason travels as
-  // data rather than as text scraped back out of a captured stream. The exit
-  // code is set before the write so a callback that never fires still fails the
-  // load, and the write's completion is what triggers the exit, because
-  // process.exit abandons a pending pipe write.
   process.exitCode = 1;
   process.stdout.write(JSON.stringify({ __ttscLoaderError: error && error.message ? String(error.message) : String(error) }), () => process.exit(1));
 });
@@ -333,7 +666,13 @@ function toSerializableBanner(value) {
   }
   ctx, cancel := context.WithCancel(context.Background())
   defer cancel()
-  cmd := exec.CommandContext(ctx, node, "-e", script, location)
+  // Windows limits the whole process command line to roughly 32 KiB. The
+  // dependency-tracking loader is intentionally larger than that, so keep only
+  // an explicit CommonJS stdin program and remove Node's stdin sentinel before
+  // the loader runs. This preserves the historical process.argv layout seen by
+  // both the loader and the imported user config without using string eval.
+  cmd := exec.CommandContext(ctx, node, "--input-type=commonjs", "-", location)
+  cmd.Stdin = strings.NewReader("process.argv.splice(1, 1);\n" + script)
   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
@@ -346,15 +685,46 @@ function toSerializableBanner(value) {
     // What it could not put there is a reason a caller can act on, so that
     // arrives through the payload channel instead.
     if reason := loaderFailureReason(output); reason != "" {
-      return nil, fmt.Errorf("@ttsc/banner: load config file %s: %s", location, reason)
+      return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: load config file %s: %s", location, reason)
     }
-    return nil, fmt.Errorf("@ttsc/banner: load config file %s: %w", location, err)
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: load config file %s: %w", location, err)
   }
-  var out any
-  if err := json.Unmarshal(output, &out); err != nil {
-    return nil, fmt.Errorf("@ttsc/banner: parse config file %s output: %w", location, err)
+  loaded, err := decodeBannerConfigLoaderOutput(output)
+  if err != nil {
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: parse config file %s output: %w", location, err)
   }
-  return out, nil
+  return loaded, nil
+}
+
+func decodeBannerConfigLoaderOutput(output []byte) (bannerLoadedConfig, error) {
+  var envelope struct {
+    Error     string             `json:"__ttscLoaderError"`
+    Hashes    map[string]*string `json:"hashes"`
+    Inputs    []string           `json:"inputs"`
+    Realpaths map[string]*string `json:"realpaths"`
+    Value     json.RawMessage    `json:"value"`
+  }
+  if err := json.Unmarshal(output, &envelope); err != nil {
+    return bannerLoadedConfig{}, err
+  }
+  if envelope.Error != "" {
+    return bannerLoadedConfig{}, fmt.Errorf("%s", envelope.Error)
+  }
+  if len(envelope.Value) == 0 {
+    // Test/fallback launchers written against the historical payload return
+    // the config value directly. Preserve that accepted contract while real
+    // loaders use the envelope to carry runtime inputs.
+    var value any
+    if err := json.Unmarshal(output, &value); err != nil {
+      return bannerLoadedConfig{}, err
+    }
+    return bannerLoadedConfig{value: value}, nil
+  }
+  var value any
+  if err := json.Unmarshal(envelope.Value, &value); err != nil {
+    return bannerLoadedConfig{}, err
+  }
+  return bannerLoadedConfig{hashes: envelope.Hashes, inputs: envelope.Inputs, realpaths: envelope.Realpaths, value: value}, nil
 }
 
 // loadBannerTypeScriptConfigFile compiles and runs a TypeScript banner config
@@ -362,29 +732,38 @@ 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) {
+  loaded, err := loadBannerTypeScriptConfigFileWithInputs(location, resolutionRoot)
+  return loaded.value, err
+}
+
+func loadBannerTypeScriptConfigFileWithInputs(location, resolutionRoot string) (bannerLoadedConfig, 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)
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: create config loader tempdir: %w", err)
   }
   defer os.RemoveAll(tempDir)
 
   if err := linkConfigNodeModules(tempDir, filepath.Dir(location)); err != nil {
-    return nil, err
+    return bannerLoadedConfig{}, err
   }
 
   loader := filepath.Join(tempDir, "loader.mts")
   tsconfig := filepath.Join(tempDir, "tsconfig.json")
   importSpecifier, err := relativeImportSpecifier(tempDir, location)
   if err != nil {
-    return nil, err
+    return bannerLoadedConfig{}, err
   }
   importLiteral, _ := json.Marshal(importSpecifier)
   if err := writeConfigLoaderFile(loader, []byte(bannerTypeScriptConfigLoaderSource(string(importLiteral))), 0o644); err != nil {
-    return nil, fmt.Errorf("@ttsc/banner: write config loader: %w", err)
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: write config loader: %w", err)
   }
   if err := writeConfigLoaderFile(tsconfig, []byte(typeScriptConfigLoaderTsconfig(loader, location, tempDir)), 0o644); err != nil {
-    return nil, fmt.Errorf("@ttsc/banner: write config loader tsconfig: %w", err)
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: write config loader tsconfig: %w", err)
   }
 
   args := []string{
@@ -393,14 +772,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
@@ -413,36 +793,232 @@ func loadBannerTypeScriptConfigFile(location string) (any, error) {
     // What it could not put there is a reason a caller can act on, so that
     // arrives through the payload channel instead.
     if reason := loaderFailureReason(output); reason != "" {
-      return nil, fmt.Errorf("@ttsc/banner: load TypeScript config file %s: %s", location, reason)
+      return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: load TypeScript config file %s: %s", location, reason)
     }
-    return nil, fmt.Errorf("@ttsc/banner: load TypeScript config file %s: %w", location, err)
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: load TypeScript config file %s: %w", location, err)
   }
-  var out any
-  if err := json.Unmarshal(output, &out); err != nil {
-    return nil, fmt.Errorf("@ttsc/banner: parse TypeScript config file %s output: %w", location, err)
-  }
-  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)
+  loaded, err := decodeBannerConfigLoaderOutput(output)
   if err != nil {
-    return "", fmt.Errorf("@ttsc/banner: resolve relative config import %s: %w", location, err)
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: parse TypeScript config file %s output: %w", location, err)
   }
-  relative = filepath.ToSlash(relative)
-  if strings.HasPrefix(relative, "../") || strings.HasPrefix(relative, "./") {
-    return relative, nil
-  }
-  return "./" + relative, nil
+  return loaded, 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.
 func bannerTypeScriptConfigLoaderSource(importLiteral string) string {
-  return fmt.Sprintf(`import * as importedConfig from %s;
+  return fmt.Sprintf(`// @ts-nocheck
+import { createRequire, isBuiltin, registerHooks } from "node:module";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const inputs = new Set<string>();
+const hashes = new Map<string, string | null>();
+const realpaths = new Map<string, string | null>();
+const signatures = new Map<string, string>();
+const unstableHashes = new Set<string>();
+
+function existingFile(file: string): boolean {
+  try { return fs.statSync(file).isFile(); }
+  catch { return false; }
+}
+
+function missingPathError(error: unknown): boolean {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function inputMetadataSignature(file: string): string | undefined {
+  const requested = path.resolve(file);
+  let current = requested;
+  for (;;) {
+    try {
+      const link = fs.lstatSync(current, { bigint: true });
+      let target = link;
+      if (link.isSymbolicLink()) {
+        try { target = fs.statSync(current, { bigint: true }); }
+        catch { return undefined; }
+      }
+      return [path.relative(current, requested), link.dev, link.ino, link.mode, link.size, link.mtimeNs, link.ctimeNs, target.dev, target.ino, target.mode, target.size, target.mtimeNs, target.ctimeNs].join(":");
+    } catch (error) {
+      if (!missingPathError(error)) return undefined;
+      const parent = path.dirname(current);
+      if (parent === current) return undefined;
+      current = parent;
+    }
+  }
+}
+
+function recordInput(file: string): void {
+  file = path.resolve(file);
+  inputs.add(file);
+  if (unstableHashes.has(file)) return;
+  const beforeSignature = inputMetadataSignature(file);
+  let observed: string | null;
+  let observedRealpath: string | null;
+  try { observed = fs.statSync(file).isDirectory() ? crypto.createHash("sha256").update("ttsc:host-input:directory\\0").digest("hex") : crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+  catch { observed = null; }
+  try { observedRealpath = fs.realpathSync.native(file); }
+  catch { observedRealpath = null; }
+  const afterSignature = inputMetadataSignature(file);
+  if (beforeSignature === undefined || afterSignature === undefined || beforeSignature !== afterSignature || (signatures.has(file) && signatures.get(file) !== afterSignature) || (hashes.has(file) && hashes.get(file) !== observed) || (realpaths.has(file) && realpaths.get(file) !== observedRealpath)) {
+    hashes.delete(file);
+    realpaths.delete(file);
+    signatures.delete(file);
+    unstableHashes.add(file);
+    return;
+  }
+  signatures.set(file, afterSignature);
+  hashes.set(file, observed);
+  realpaths.set(file, observedRealpath);
+}
+
+function recordFile(file: string): void {
+  const resolvedFile = path.resolve(file);
+  recordInput(resolvedFile);
+  for (let directory = path.dirname(resolvedFile);;) {
+    const manifest = path.join(directory, "package.json");
+    recordInput(manifest);
+    if (existingFile(manifest)) {
+      break;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      break;
+    }
+    directory = parent;
+  }
+}
+
+function recordPackageManifests(file: string): void {
+  for (let directory = path.dirname(path.resolve(file));;) {
+    const manifest = path.join(directory, "package.json");
+    recordInput(manifest);
+    if (existingFile(manifest)) return;
+    const parent = path.dirname(directory);
+    if (parent === directory) return;
+    directory = parent;
+  }
+}
+
+const moduleProbeExtensions = [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json", ".node"] as const;
+const jsToTsProbeExtensions = new Map<string, readonly string[]>([
+  [".js", [".ts", ".tsx"]],
+  [".jsx", [".tsx"]],
+  [".mjs", [".mts"]],
+  [".cjs", [".cts"]],
+]);
+function sourceSubstitutionCandidates(base: string): string[] {
+  const extension = path.extname(base).toLowerCase();
+  const substitutions = jsToTsProbeExtensions.get(extension);
+  if (substitutions === undefined) return [];
+  const stem = base.slice(0, base.length - extension.length);
+  return substitutions.map((candidate) => stem + candidate);
+}
+function moduleCandidates(base: string): string[] {
+  return [
+    base,
+    ...sourceSubstitutionCandidates(base),
+    ...moduleProbeExtensions.map((extension) => base + extension),
+    path.join(base, "package.json"),
+    ...moduleProbeExtensions.map((extension) => path.join(base, "index" + extension)),
+  ];
+}
+const recordedModuleBases = new Set<string>();
+function recordManifestTargets(value: unknown, directory: string, allowBare: boolean = false): void {
+  if (typeof value === "string") {
+    if (value !== "" && (allowBare || value.startsWith("./") || value.startsWith("../"))) recordModuleCandidates(path.resolve(directory, value));
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) recordManifestTargets(item, directory, allowBare);
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    for (const item of Object.values(value)) recordManifestTargets(item, directory, allowBare);
+  }
+}
+function recordModuleCandidates(base: string): void {
+  const resolvedBase = path.resolve(base);
+  if (recordedModuleBases.has(resolvedBase)) return;
+  recordedModuleBases.add(resolvedBase);
+  for (const candidate of moduleCandidates(resolvedBase)) recordInput(candidate);
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(resolvedBase, "package.json"), "utf8").replace(/^\uFEFF/, ""));
+    recordManifestTargets(manifest.exports, resolvedBase);
+    recordManifestTargets(manifest.module, resolvedBase, true);
+    recordManifestTargets(manifest.main, resolvedBase, true);
+  } catch {}
+}
+function candidateSelected(base: string, resolvedFile: string): boolean {
+  for (const candidate of moduleCandidates(base)) {
+    try {
+      const canonical = fs.realpathSync.native(candidate);
+      const relative = path.relative(canonical, resolvedFile);
+      if (relative === "" || (fs.statSync(canonical).isDirectory() && relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative))) return true;
+    } catch {}
+  }
+  return false;
+}
+function localBases(specifier: string, parentDirectory: string): string[] {
+  if (specifier.startsWith("file:")) return [fileURLToPath(specifier)];
+  const raw = path.resolve(parentDirectory, specifier);
+  const suffixStart = specifier.search(/[?#]/);
+  if (suffixStart === -1) return [raw];
+  const pathname = specifier.slice(0, suffixStart);
+  return pathname === "" ? [raw] : [...new Set([raw, path.resolve(parentDirectory, pathname)])];
+}
+function recordResolutionCandidates(specifier: string, parentURL: string | undefined, resolvedURL: string | undefined): void {
+  if (typeof parentURL !== "string" || !parentURL.startsWith("file:")) return;
+  const parentDirectory = path.dirname(fileURLToPath(parentURL));
+  let resolvedFile: string | undefined;
+  try {
+    resolvedFile = typeof resolvedURL === "string" && resolvedURL.startsWith("file:")
+      ? fs.realpathSync.native(fileURLToPath(resolvedURL))
+      : undefined;
+  } catch {}
+  if (specifier.startsWith(".") || path.isAbsolute(specifier) || specifier.startsWith("file:")) {
+    try {
+      for (const base of localBases(specifier, parentDirectory)) {
+        recordPackageManifests(base);
+        let exact = false;
+        try { exact = resolvedFile === undefined ? fs.statSync(base).isFile() : fs.realpathSync.native(base) === resolvedFile; } catch {}
+        if (exact) recordInput(base);
+        else recordModuleCandidates(base);
+      }
+    } catch {}
+    return;
+  }
+  if (isBuiltin(specifier) || specifier.startsWith("#")) return;
+  const parts = specifier.split("/");
+  const packageParts = parts[0]!.startsWith("@") ? parts.slice(0, 2) : parts.slice(0, 1);
+  if (packageParts.some((part) => part === undefined || part === "")) return;
+  const packageName = packageParts.join("/");
+  const subpath = parts.slice(packageParts.length);
+  const searchPaths = createRequire(parentURL).resolve.paths(specifier) ?? [];
+  for (const searchPath of searchPaths) {
+    const packageDirectory = path.join(searchPath, packageName);
+    recordModuleCandidates(packageDirectory);
+    if (subpath.length !== 0) recordModuleCandidates(path.join(packageDirectory, ...subpath));
+    if (resolvedFile !== undefined && candidateSelected(packageDirectory, resolvedFile)) break;
+  }
+}
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    recordResolutionCandidates(specifier, context.parentURL, undefined);
+    const resolved = nextResolve(specifier, context);
+    const url = typeof resolved === "string" ? resolved : resolved?.url;
+    recordResolutionCandidates(specifier, context.parentURL, url);
+    if (typeof url === "string" && url.startsWith("file:")) {
+      recordFile(fileURLToPath(url));
+    }
+    return resolved;
+  },
+});
 
 declare const process: {
   exitCode?: number;
@@ -458,8 +1034,16 @@ declare const process: {
 // left for a trailing handler to settle.
 (async () => {
   try {
+    const importedConfig = await import(%s);
     const value = await resolveConfig(importedConfig);
-    process.stdout.write(JSON.stringify(toSerializableBanner(value)));
+    const serializedValue = toSerializableBanner(value);
+    for (const input of [...inputs]) recordInput(input);
+    process.stdout.write(JSON.stringify({
+      value: serializedValue,
+      hashes: Object.fromEntries(hashes),
+      inputs: [...inputs].sort(),
+      realpaths: Object.fromEntries(realpaths),
+    }));
   } catch (error) {
     process.stderr.write(error instanceof Error && error.stack ? error.stack : String(error));
     // The stack above is for the reader. This is for the caller: the parent
@@ -529,6 +1113,7 @@ func typeScriptConfigLoaderTsconfig(loader, location, outDir string) string {
       // resolving either way.
       "module":                          configModuleOption(location),
       "moduleResolution":                "bundler",
+      "jsx":                             "preserve",
       "outDir":                          filepath.ToSlash(filepath.Join(outDir, "out")),
       "rewriteRelativeImportExtensions": true,
       "rootDir":                         loaderRootDir(outDir),
@@ -551,6 +1136,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 +1275,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 +1592,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 +1619,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 +1638,5 @@ func loaderFailureReason(output []byte) string {
   }
   return strings.TrimSpace(envelope.Message)
 }
+
+// ttsc:config-loader-shared end