@ttsc/banner 0.26.2 → 0.28.0

package/driver/banner.go

@@ -3,6 +3,7 @@ package banner
 import (
   "bytes"
   "context"
+  "crypto/sha256"
   "encoding/json"
   "fmt"
   "os"
@@ -61,13 +62,32 @@ 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)
+  preamble, err := parseBannerWithReporters(ctx.Entry.Config, ctx.Cwd, ctx.Tsconfig, ctx.ReportHostInput, ctx.ReportHostInputHash, ctx.ReportHostInputRealpath)
+  if err != nil {
+    return "", err
+  }
+  // Every file receives the same text, and that text comes from
+  // banner.config.* alone — including, for a script or TypeScript config, every
+  // module the loader pulled in, each of which was reported above as a host
+  // input. Host inputs stay universal under the completeness contract, so a
+  // config edit still invalidates every file while an unrelated type edit stops
+  // doing so (samchon/ttsc#1263).
+  ctx.ReportDependenciesComplete()
+  return preamble, nil
 }
 
 // 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
   }
@@ -108,6 +128,14 @@ func sanitizeJSDocLine(line string) string {
 // 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
   }
@@ -119,11 +147,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, resolutionRoot)
+    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
     }
@@ -133,18 +162,24 @@ func resolveBannerText(config map[string]any, cwd, tsconfigPath string) (string,
     return text, nil
   }
 
-  location, err := findBannerConfigFile(cwd, tsconfigPath)
+  location, probed, err := findBannerConfigFile(cwd, tsconfigPath)
+  // Report the rejected candidates before the error checks: a search that ended
+  // ambiguous or empty examined them just the same, and a consumer that learns
+  // of them can invalidate a generation the next search would answer
+  // differently.
+  driver.ReportRejectedConfigCandidates(probed, hashReporter, realpathReporter)
   if err != nil {
     return "", err
   }
   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, resolutionRoot)
+  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
   }
@@ -179,47 +214,45 @@ func bannerTextFromConfigValue(raw any, label string) (string, bool, error) {
   return text, true, nil
 }
 
+// bannerConfigFilenames is the discovery name list, in precedence order.
+var bannerConfigFilenames = []string{
+  "banner.config.json",
+  "banner.config.js",
+  "banner.config.cjs",
+  "banner.config.mjs",
+  "banner.config.ts",
+  "banner.config.cts",
+  "banner.config.mts",
+}
+
 // findBannerConfigFile walks up from the tsconfig (or cwd) directory looking for
 // a banner.config.{ts,cts,mts,js,cjs,mjs,json} file. Returns the path when exactly
 // one match is found per directory, "" when none exists at any level, or an
 // error when multiple candidates exist in the same directory.
-func findBannerConfigFile(cwd, tsconfigPath string) (string, error) {
-  dir := tsconfigBaseDir(cwd, tsconfigPath)
-  for {
-    matches := make([]string, 0, 1)
-    for _, name := range []string{
-      "banner.config.json",
-      "banner.config.js",
-      "banner.config.cjs",
-      "banner.config.mjs",
-      "banner.config.ts",
-      "banner.config.cts",
-      "banner.config.mts",
-    } {
-      candidate := filepath.Join(dir, name)
-      if stat, err := os.Stat(candidate); err == nil && !stat.IsDir() {
-        matches = append(matches, candidate)
-      }
-    }
-    if len(matches) > 1 {
-      names := make([]string, len(matches))
-      for i, match := range matches {
-        names[i] = filepath.Base(match)
-      }
-      return "", fmt.Errorf(
-        "@ttsc/banner: multiple banner config files found in %s (%s); set \"configFile\" explicitly in the tsconfig plugin entry",
-        dir, strings.Join(names, ", "),
-      )
-    }
-    if len(matches) == 1 {
-      return matches[0], nil
-    }
-    parent := filepath.Dir(dir)
-    if parent == dir {
-      return "", nil
+//
+// The second return value is every candidate the walk examined and rejected,
+// each carrying whether it was absent or a directory wearing the name. Those
+// paths decide the result as much as the file it returned: one
+// created nearer the entry wins the next search outright, and one created
+// beside the match makes that directory ambiguous. The caller reports them so a
+// persistent consumer stops serving output built from a config a cold run would
+// no longer choose (samchon/ttsc#1271).
+func findBannerConfigFile(cwd, tsconfigPath string) (string, []driver.ConfigCandidate, error) {
+  discovery := driver.DiscoverConfigFile(tsconfigBaseDir(cwd, tsconfigPath), bannerConfigFilenames)
+  if len(discovery.Matches) > 1 {
+    names := make([]string, len(discovery.Matches))
+    for i, match := range discovery.Matches {
+      names[i] = filepath.Base(match)
     }
-    dir = parent
+    return "", discovery.Probed, fmt.Errorf(
+      "@ttsc/banner: multiple banner config files found in %s (%s); set \"configFile\" explicitly in the tsconfig plugin entry",
+      discovery.Directory, strings.Join(names, ", "),
+    )
+  }
+  if len(discovery.Matches) == 1 {
+    return discovery.Matches[0], discovery.Probed, nil
   }
+  return "", discovery.Probed, nil
 }
 
 // resolveBannerConfigPath resolves a config path from the plugin entry.
@@ -253,17 +286,118 @@ func tsconfigBaseDir(cwd, tsconfigPath string) string {
 // 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, resolutionRoot)
 }
 
 // isBannerConfigFileName reports whether name is an allowed banner config file name.
@@ -290,6 +424,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})
@@ -304,8 +442,235 @@ 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 nodeModule = require("node:module");
+const { createRequire, isBuiltin, registerHooks } = nodeModule;
+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;
+  },
+});
+
+// The hook above never sees a require() made from inside a CommonJS module the
+// ESM loader evaluated, which on Node 22 is every require the config makes:
+// module.registerHooks observes the import() of that module and nothing within
+// it. A config's own dependencies would then be reported without the candidates
+// that decide them, so a spelling appearing later could change what the config
+// resolves to with nothing in the envelope to notice it (samchon/ttsc#1280).
+// Wrapping the CommonJS resolver records the same two observations the hook
+// does, on the graph the hook cannot reach.
+const nextResolveFilename = nodeModule._resolveFilename;
+nodeModule._resolveFilename = function resolveFilename(request, parent, isMain, options) {
+  // _resolveFilename is an internal entry point anything may call, so a
+  // non-string request arrives here as readily as a specifier does. Reading it
+  // would replace Node's own argument error with a TypeError from this loader.
+  if (typeof request !== "string") {
+    return nextResolveFilename.call(this, request, parent, isMain, options);
+  }
+  const parentFile = parent && typeof parent.filename === "string" ? parent.filename : undefined;
+  const parentURL = parentFile === undefined ? undefined : pathToFileURL(parentFile).href;
+  recordResolutionCandidates(request, parentURL, undefined);
+  const resolved = nextResolveFilename.call(this, request, parent, isMain, options);
+  if (path.isAbsolute(resolved)) {
+    recordResolutionCandidates(request, parentURL, pathToFileURL(resolved).href);
+    recordFile(resolved);
+  }
+  return resolved;
+};
 
 (async () => {
   const mod = await import(pathToFileURL(process.argv[1]).href);
@@ -321,15 +686,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));
 });
@@ -347,7 +708,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
@@ -360,15 +727,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
@@ -381,28 +779,33 @@ function toSerializableBanner(value) {
 // 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{
@@ -432,22 +835,275 @@ func loadBannerTypeScriptConfigFile(location, resolutionRoot 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)
+  loaded, err := decodeBannerConfigLoaderOutput(output)
+  if err != nil {
+    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: parse TypeScript config file %s output: %w", location, err)
   }
-  return out, 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 Module, { createRequire, isBuiltin, registerHooks } from "node:module";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } 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;
+  },
+});
+
+// The hook above never sees a require() made from inside a CommonJS module the
+// ESM loader evaluated, which on Node 22 is every require the config makes:
+// module.registerHooks observes the import() of that module and nothing within
+// it. A config's own dependencies would then be reported without the candidates
+// that decide them, so a spelling appearing later could change what the config
+// resolves to with nothing in the envelope to notice it (samchon/ttsc#1280).
+// Wrapping the CommonJS resolver records the same two observations the hook
+// does, on the graph the hook cannot reach.
+const moduleInternals = Module as unknown as {
+  _resolveFilename(
+    request: string,
+    parent: { filename?: string | null } | null | undefined,
+    isMain: boolean,
+    options?: unknown,
+  ): string;
+};
+const nextResolveFilename = moduleInternals._resolveFilename;
+moduleInternals._resolveFilename = function resolveFilename(
+  this: unknown,
+  request: string,
+  parent: { filename?: string | null } | null | undefined,
+  isMain: boolean,
+  options?: unknown,
+): string {
+  // _resolveFilename is an internal entry point anything may call, so a
+  // non-string request arrives here as readily as a specifier does. Reading it
+  // would replace Node's own argument error with a TypeError from this loader.
+  if (typeof request !== "string") {
+    return nextResolveFilename.call(this, request, parent, isMain, options);
+  }
+  const parentURL =
+    typeof parent?.filename === "string"
+      ? pathToFileURL(parent.filename).href
+      : undefined;
+  recordResolutionCandidates(request, parentURL, undefined);
+  const resolved = nextResolveFilename.call(this, request, parent, isMain, options);
+  if (path.isAbsolute(resolved)) {
+    recordResolutionCandidates(request, parentURL, pathToFileURL(resolved).href);
+    recordFile(resolved);
+  }
+  return resolved;
+};
 
 declare const process: {
   exitCode?: number;
@@ -463,8 +1119,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
@@ -534,6 +1198,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),

package/lib/index.js

@@ -18,6 +18,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = createTtscBanner;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 __exportStar(require("./structures/index"), exports);
 /**
@@ -51,7 +53,11 @@ function createTtscBanner(context) {
                 `The only accepted key in the tsconfig entry is "configFile" (optional path to the config file).`);
         }
     }
+    const configInputs = bannerConfigInputs(context);
     return {
+        hostInputHashes: configInputs.hashes,
+        hostInputRealpaths: configInputs.realpaths,
+        hostInputs: configInputs.inputs,
         name: "@ttsc/banner",
         // Point at the `driver/` directory one level above `lib/` in the
         // installed package tree (where the Go sources live). `context.dirname`
@@ -61,4 +67,83 @@ function createTtscBanner(context) {
         stage: "transform",
     };
 }
+const BANNER_CONFIG_FILENAMES = [
+    "banner.config.json",
+    "banner.config.js",
+    "banner.config.cjs",
+    "banner.config.mjs",
+    "banner.config.ts",
+    "banner.config.cts",
+    "banner.config.mts",
+];
+/** Mirror native config resolution while retaining missing priority probes. */
+function bannerConfigInputs(context) {
+    const configFile = context.plugin.configFile;
+    const base = node_path_1.default.resolve(context.pluginConfigDir ?? node_path_1.default.dirname(context.tsconfig));
+    if (typeof configFile === "string" && configFile.trim() !== "") {
+        const file = node_path_1.default.isAbsolute(configFile)
+            ? node_path_1.default.resolve(configFile)
+            : node_path_1.default.resolve(base, configFile);
+        return {
+            hashes: { [file]: hostInputHash(file) },
+            inputs: [file],
+            realpaths: { [file]: hostInputRealpath(file) },
+        };
+    }
+    return configDiscoveryInputs(base, BANNER_CONFIG_FILENAMES);
+}
+function configDiscoveryInputs(base, names) {
+    const inputs = [];
+    const hashes = {};
+    const realpaths = {};
+    for (let directory = base;; directory = node_path_1.default.dirname(directory)) {
+        const candidates = names.map((name) => node_path_1.default.join(directory, name));
+        inputs.push(...candidates);
+        for (const candidate of candidates) {
+            hashes[candidate] = hostInputHash(candidate);
+            realpaths[candidate] = hostInputRealpath(candidate);
+        }
+        if (candidates.some(configCandidateExists))
+            break;
+        const parent = node_path_1.default.dirname(directory);
+        if (parent === directory)
+            break;
+    }
+    return { hashes, inputs, realpaths };
+}
+function hostInputRealpath(file) {
+    try {
+        return node_fs_1.default.realpathSync.native(file);
+    }
+    catch {
+        return null;
+    }
+}
+/** Hash the exact candidate state observed before discovery selects a file. */
+function hostInputHash(file) {
+    try {
+        if (node_fs_1.default.statSync(file).isDirectory()) {
+            return node_crypto_1.default
+                .createHash("sha256")
+                .update("ttsc:host-input:directory\0")
+                .digest("hex");
+        }
+        return node_crypto_1.default
+            .createHash("sha256")
+            .update(node_fs_1.default.readFileSync(file))
+            .digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/** Match the native discovery rule: a directory is never a config file. */
+function configCandidateExists(file) {
+    try {
+        return !node_fs_1.default.statSync(file).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,0DAA6B;AAI7B,qDAAmC;AAmDnC;;;;GAIG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAS;IACrC,SAAS;IACT,MAAM;IACN,OAAO;IACP,WAAW;CACZ,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,0BACE,OAA0D;IAE1D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAiC,CAAC;IACxD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,gEAAgE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI;gBACrF,sFAAsF;gBACtF,iGAAiG,CACpG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,iEAAiE;QACjE,wEAAwE;QACxE,oEAAoE;QACpE,6EAA6E;QAC7E,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC;QACrD,KAAK,EAAE,WAAW;KACnB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/banner",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "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.2"
+    "ttsc": "0.28.0"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
 import path from "node:path";
 
 import type { ITtscBannerPluginConfig } from "./structures";
@@ -12,6 +14,12 @@ export * from "./structures/index";
  * executable sidecar or linked native source.
  */
 type TtscPluginDescriptor = {
+  /** Universal config-discovery inputs consumed by the native transform. */
+  hostInputs?: string[];
+  /** Evaluation-time fingerprints paired with {@link hostInputs}. */
+  hostInputHashes?: Record<string, string | null>;
+  /** Evaluation-time physical targets paired with {@link hostInputs}. */
+  hostInputRealpaths?: Record<string, string | null>;
   /** Human-readable plugin name used in logs and error messages. */
   name: string;
   /** Absolute path to the Go source directory for this plugin. */
@@ -45,6 +53,8 @@ type TtscPluginFactoryContext<TConfig> = {
    * replacement for `__filename`.
    */
   filename: string;
+  /** Host-declared anchor for implicit plugin config discovery. */
+  pluginConfigDir?: string;
   /** The raw plugin entry from `compilerOptions.plugins[]`. */
   plugin: TConfig;
   /** Absolute path to the project root (directory containing tsconfig). */
@@ -90,7 +100,11 @@ export default function createTtscBanner(
     }
   }
 
+  const configInputs = bannerConfigInputs(context);
   return {
+    hostInputHashes: configInputs.hashes,
+    hostInputRealpaths: configInputs.realpaths,
+    hostInputs: configInputs.inputs,
     name: "@ttsc/banner",
     // Point at the `driver/` directory one level above `lib/` in the
     // installed package tree (where the Go sources live). `context.dirname`
@@ -100,3 +114,98 @@ export default function createTtscBanner(
     stage: "transform",
   };
 }
+
+const BANNER_CONFIG_FILENAMES = [
+  "banner.config.json",
+  "banner.config.js",
+  "banner.config.cjs",
+  "banner.config.mjs",
+  "banner.config.ts",
+  "banner.config.cts",
+  "banner.config.mts",
+];
+
+/** Mirror native config resolution while retaining missing priority probes. */
+function bannerConfigInputs(
+  context: TtscPluginFactoryContext<ITtscBannerPluginConfig>,
+): {
+  hashes: Record<string, string | null>;
+  inputs: string[];
+  realpaths: Record<string, string | null>;
+} {
+  const configFile = (context.plugin as { configFile?: unknown }).configFile;
+  const base = path.resolve(
+    context.pluginConfigDir ?? path.dirname(context.tsconfig),
+  );
+  if (typeof configFile === "string" && configFile.trim() !== "") {
+    const file = path.isAbsolute(configFile)
+      ? path.resolve(configFile)
+      : path.resolve(base, configFile);
+    return {
+      hashes: { [file]: hostInputHash(file) },
+      inputs: [file],
+      realpaths: { [file]: hostInputRealpath(file) },
+    };
+  }
+  return configDiscoveryInputs(base, BANNER_CONFIG_FILENAMES);
+}
+
+function configDiscoveryInputs(
+  base: string,
+  names: readonly string[],
+): {
+  hashes: Record<string, string | null>;
+  inputs: string[];
+  realpaths: Record<string, string | null>;
+} {
+  const inputs: string[] = [];
+  const hashes: Record<string, string | null> = {};
+  const realpaths: Record<string, string | null> = {};
+  for (let directory = base; ; directory = path.dirname(directory)) {
+    const candidates = names.map((name) => path.join(directory, name));
+    inputs.push(...candidates);
+    for (const candidate of candidates) {
+      hashes[candidate] = hostInputHash(candidate);
+      realpaths[candidate] = hostInputRealpath(candidate);
+    }
+    if (candidates.some(configCandidateExists)) break;
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+  }
+  return { hashes, inputs, realpaths };
+}
+
+function hostInputRealpath(file: string): string | null {
+  try {
+    return fs.realpathSync.native(file);
+  } catch {
+    return null;
+  }
+}
+
+/** Hash the exact candidate state observed before discovery selects a file. */
+function hostInputHash(file: string): string | null {
+  try {
+    if (fs.statSync(file).isDirectory()) {
+      return crypto
+        .createHash("sha256")
+        .update("ttsc:host-input:directory\0")
+        .digest("hex");
+    }
+    return crypto
+      .createHash("sha256")
+      .update(fs.readFileSync(file))
+      .digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/** Match the native discovery rule: a directory is never a config file. */
+function configCandidateExists(file: string): boolean {
+  try {
+    return !fs.statSync(file).isDirectory();
+  } catch {
+    return false;
+  }
+}