@ttsc/banner 0.30.4 → 0.31.0

package/driver/banner.go

@@ -13,6 +13,7 @@ import (
   "strings"
 
   "github.com/samchon/ttsc/packages/ttsc/driver"
+  "github.com/samchon/ttsc/packages/ttsc/driver/resolutioninputs"
   "github.com/samchon/ttsc/packages/ttsc/driver/windowsjunction"
 )
 
@@ -23,13 +24,6 @@ func init() {
 // plugin implements driver.SourcePreamblePlugin for @ttsc/banner.
 type plugin struct{}
 
-var (
-  // linkConfigNodeModules is overridable in tests to avoid real symlink creation.
-  linkConfigNodeModules = linkNearestNodeModules
-  // writeConfigLoaderFile is overridable in tests to avoid real file I/O.
-  writeConfigLoaderFile = os.WriteFile
-)
-
 // frameworkKeys lists the tsconfig plugin-entry keys that the ttsc host
 // framework owns. They are accepted without error; all other keys are rejected.
 var frameworkKeys = map[string]struct{}{
@@ -60,9 +54,31 @@ 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.
+// formatted as JSDoc source for the host to prepend before parsing.
+//
+// Failure returns no preamble and does not report dependency completeness.
+// Successful evaluation reports universal config inputs because the same banner
+// text applies to every file. The host invokes this operation once per Program,
+// then its filesystem wrapper injects the returned text and applies emit policy.
+//
+// CRLF normalization, trailing blank-line removal and closing-delimiter escaping
+// make consumer text a closed comment. The host owns placement, authored-position
+// remapping and removeComments. Discovery probes seven names per ancestor, then
+// parsing and formatting process the config/banner bytes linearly.
+//
+// JSON loads need no child. Executable config uses a child process and TypeScript
+// also owns a temporary directory, removed by defer. stderr streams to the
+// parent; stdout has no byte cap and evaluation has no deadline. Cleanup errors
+// are not reported. Successful loader output must carry dependency observations;
+// unsupported public resolution observation is reported separately from input
+// mutation, so fresh evaluation can succeed without claiming reusable inputs.
+//
+// Native paths use filepath; slash conversion is reserved for import/tsconfig
+// spelling. Child arguments are separate from executable paths. A loader's temp
+// directory stays on the config volume, with Windows junctions used when native
+// symlink creation is unavailable.
 func (plugin) SourcePreamble(ctx driver.PluginContext) (string, error) {
-  preamble, err := parseBannerWithReporters(ctx.Entry.Config, ctx.Cwd, ctx.Tsconfig, ctx.ReportHostInput, ctx.ReportHostInputHash, ctx.ReportHostInputRealpath)
+  preamble, err := parseBannerWithReporters(ctx.Entry.Config, ctx.Cwd, ctx.Tsconfig, ctx.ReportHostInput, ctx.ReportHostInputHash, ctx.ReportHostInputRealpath, ctx.ReportObservationIncomplete)
   if err != nil {
     return "", err
   }
@@ -76,18 +92,13 @@ func (plugin) SourcePreamble(ctx driver.PluginContext) (string, error) {
   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) {
-  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)
+// parseBannerWithReporters resolves banner text and formats it as a JSDoc block
+// comment, stripping trailing blank lines first, while forwarding exact config
+// witnesses.
+// Optional incomplete reporters disclose unavailable public resolution observation
+// without deleting known witnesses or treating an evaluated value as a failure.
+func parseBannerWithReporters(config map[string]any, cwd, tsconfigPath string, reporter func(string), hashReporter func(string, *string), realpathReporter func(string, *string), incompleteReporters ...func()) (string, error) {
+  text, err := resolveBannerTextWithReporters(config, cwd, tsconfigPath, reporter, hashReporter, realpathReporter, incompleteReporters...)
   if err != nil {
     return "", err
   }
@@ -118,24 +129,18 @@ 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
+// resolveBannerTextWithReporters extracts the banner text from the plugin
+// config. The 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.
+// resolved to an absolute path and loaded; when absent the upward-walk
+// discovery is used. Returns an error when the config is invalid or 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) {
+// The discovery base directory doubles as the resolution root the config loader
+// anchors its toolchain lookup on; see configToolAnchors. Configuration value
+// loading stays separate from observation capability: incomplete reports cannot
+// restore a missing input proof.
+func resolveBannerTextWithReporters(config map[string]any, cwd, tsconfigPath string, reporter func(string), hashReporter func(string, *string), realpathReporter func(string, *string), incompleteReporters ...func()) (string, error) {
   if err := validateBannerConfig(config); err != nil {
     return "", err
   }
@@ -152,6 +157,13 @@ func resolveBannerTextWithReporters(config map[string]any, cwd, tsconfigPath str
       return "", err
     }
     reportBannerConfigInputs(loaded.inputs, loaded.hashes, loaded.realpaths, reporter, hashReporter, realpathReporter)
+    if !loaded.complete {
+      for _, report := range incompleteReporters {
+        if report != nil {
+          report()
+        }
+      }
+    }
     text, ok, err := bannerTextFromConfigValue(loaded.value, filepath.Base(location))
     if err != nil {
       return "", err
@@ -179,6 +191,13 @@ func resolveBannerTextWithReporters(config map[string]any, cwd, tsconfigPath str
     return "", err
   }
   reportBannerConfigInputs(loaded.inputs, loaded.hashes, loaded.realpaths, reporter, hashReporter, realpathReporter)
+  if !loaded.complete {
+    for _, report := range incompleteReporters {
+      if report != nil {
+        report()
+      }
+    }
+  }
   text, ok, err := bannerTextFromConfigValue(loaded.value, filepath.Base(location))
   if err != nil {
     return "", err
@@ -214,7 +233,8 @@ func bannerTextFromConfigValue(raw any, label string) (string, bool, error) {
   return text, true, nil
 }
 
-// bannerConfigFilenames is the discovery name list, in precedence order.
+// bannerConfigFilenames lists supported discovery names. Multiple files in one
+// directory are ambiguous; this order does not select a preferred format.
 var bannerConfigFilenames = []string{
   "banner.config.json",
   "banner.config.js",
@@ -275,28 +295,26 @@ func tsconfigBaseDir(cwd, tsconfigPath string) string {
   return driver.PluginConfigBaseDir(cwd, tsconfigPath)
 }
 
-// loadBannerConfigFile loads and evaluates a banner config file, returning its
-// exported value as a Go any. A valid banner config exports an object with a
-// "text" string; the value is validated by bannerTextFromConfigValue. The file
-// 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.
-//
-// 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 {
+  // complete concerns resolution capability; missing per-input proofs still signal instability.
+  complete bool
+
   hashes    map[string]*string
   inputs    []string
   realpaths map[string]*string
   value     any
 }
 
+// loadBannerConfigFileWithInputs loads and evaluates a banner config file and
+// returns its exported value with the input observations of the load. The file
+// 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. The value is validated by
+// bannerTextFromConfigValue, not here.
+//
+// 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 loadBannerConfigFileWithInputs(location, resolutionRoot string) (bannerLoadedConfig, error) {
   if !isBannerConfigFileName(filepath.Base(location)) {
     return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: config file must be named banner.config.{ts,cts,mts,js,cjs,mjs,json}: %s", location)
@@ -310,7 +328,7 @@ func loadBannerConfigFileWithInputs(location, resolutionRoot string) (bannerLoad
     }
     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
+    return bannerLoadedConfig{complete: true, hashes: map[string]*string{location: &digest}, inputs: []string{location}, realpaths: map[string]*string{location: physicalHostInput(location)}, value: value}, err
   case ".js", ".cjs", ".mjs":
     return loadBannerScriptConfigFileWithInputs(location)
   }
@@ -416,17 +434,10 @@ func isBannerConfigFileName(name string) bool {
   }
 }
 
-// loadBannerJSONConfigFile reads and JSON-parses a banner config file. A leading
-// UTF-8 BOM is stripped before parsing so files saved by Windows editors are
-// accepted. The parsed value must be an object with a non-empty "text" string.
-func loadBannerJSONConfigFile(location string) (any, error) {
-  body, err := os.ReadFile(location)
-  if err != nil {
-    return nil, fmt.Errorf("@ttsc/banner: read config file %s: %w", location, err)
-  }
-  return parseBannerJSONConfigFile(location, body)
-}
-
+// parseBannerJSONConfigFile parses a banner config file already read from
+// location. A leading UTF-8 BOM is stripped first so files saved by Windows
+// editors are accepted; object and text validation belong to
+// bannerTextFromConfigValue.
 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.
@@ -438,239 +449,22 @@ func parseBannerJSONConfigFile(location string, body []byte) (any, error) {
   return out, nil
 }
 
-// loadBannerScriptConfigFile evaluates a JS/CJS/MJS banner config file by
-// 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
-}
-
+// loadBannerScriptConfigFileWithInputs evaluates a JS/CJS/MJS banner config file
+// by running a small Node.js loader script that dynamic-imports the file and
+// serializes its exported value, with the loader's input observations, to stdout.
 func loadBannerScriptConfigFileWithInputs(location string) (bannerLoadedConfig, error) {
   const script = `
-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;
-};
+const { pathToFileURL } = require("node:url");
+// Which inputs a resolution read is the one rule ttsc owns
+// (resolutioninputs.Recorder), evaluated before any hook is installed.
+const { createResolutionInputRecorder, observeResolutions } = RESOLUTION_INPUT_RECORDER;
+const recorder = createResolutionInputRecorder({ extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json", ".node"] });
+
+recorder.recordFile(process.argv[1]);
+// Every resolution the config makes is recorded: through a resolve hook, and
+// on a runtime whose require.resolve bypasses the hooks, through the one
+// entry point it reaches (resolutioninputs.Recorder, samchon/ttsc#1523).
+observeResolutions(recorder);
 
 (async () => {
   const mod = await import(pathToFileURL(process.argv[1]).href);
@@ -687,8 +481,8 @@ nodeModule._resolveFilename = function resolveFilename(request, parent, isMain,
   }
   const value = typeof current === "function" ? await current() : current;
   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) }));
+  const recorded = recorder.finish();
+  process.stdout.write(JSON.stringify({ value: serializedValue, complete: recorded.complete, hashes: recorded.hashes, inputs: recorded.inputs, realpaths: recorded.realpaths }));
 })().catch((error) => {
   process.stderr.write(error && error.stack ? error.stack : String(error));
   process.exitCode = 1;
@@ -714,7 +508,10 @@ function toSerializableBanner(value) {
   // 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.Stdin = strings.NewReader(
+    "process.argv.splice(1, 1);\nconst RESOLUTION_INPUT_RECORDER = " +
+      resolutioninputs.CommonJSExpression() + ";\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
@@ -738,8 +535,14 @@ function toSerializableBanner(value) {
   return loaded, nil
 }
 
+// decodeBannerConfigLoaderOutput requires the value and recorder snapshot from
+// the executed loader. Accepting a bare value would report complete dependency
+// observations even though no observations were returned. Missing probe values
+// remain legitimate nullable entries inside the snapshot maps.
 func decodeBannerConfigLoaderOutput(output []byte) (bannerLoadedConfig, error) {
   var envelope struct {
+    Complete *bool `json:"complete"`
+
     Error     string             `json:"__ttscLoaderError"`
     Hashes    map[string]*string `json:"hashes"`
     Inputs    []string           `json:"inputs"`
@@ -752,37 +555,25 @@ func decodeBannerConfigLoaderOutput(output []byte) (bannerLoadedConfig, error) {
   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
+  if len(envelope.Value) == 0 || envelope.Complete == nil || envelope.Inputs == nil || envelope.Hashes == nil || envelope.Realpaths == nil {
+    return bannerLoadedConfig{}, fmt.Errorf("config loader must return a value with dependency observations")
   }
   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
+  return bannerLoadedConfig{complete: *envelope.Complete, hashes: envelope.Hashes, inputs: envelope.Inputs, realpaths: envelope.Realpaths, value: value}, nil
 }
 
-// loadBannerTypeScriptConfigFile compiles and runs a TypeScript banner config
-// file using ttsx in a temp directory. A symlink to the nearest node_modules
-// 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
+// loadBannerTypeScriptConfigFileWithInputs compiles and runs a TypeScript banner
+// config file using ttsx in a temp directory. A symlink to the nearest
+// node_modules 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.
 //
-// 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
-}
-
+// 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 loadBannerTypeScriptConfigFileWithInputs(location, resolutionRoot string) (bannerLoadedConfig, error) {
   tempDir, err := os.MkdirTemp(loaderTempBase(location, os.TempDir()), "ttsc-banner-config-")
   if err != nil {
@@ -790,23 +581,12 @@ func loadBannerTypeScriptConfigFileWithInputs(location, resolutionRoot string) (
   }
   defer os.RemoveAll(tempDir)
 
-  if err := linkConfigNodeModules(tempDir, filepath.Dir(location)); err != nil {
-    return bannerLoadedConfig{}, err
-  }
-
-  loader := filepath.Join(tempDir, "loader.mts")
-  tsconfig := filepath.Join(tempDir, "tsconfig.json")
-  importSpecifier, err := relativeImportSpecifier(tempDir, location)
+  loader, tsconfig, err := prepareBannerTypeScriptConfigLoader(
+    tempDir, location, linkNearestNodeModules, os.WriteFile,
+  )
   if err != nil {
     return bannerLoadedConfig{}, err
   }
-  importLiteral, _ := json.Marshal(importSpecifier)
-  if err := writeConfigLoaderFile(loader, []byte(bannerTypeScriptConfigLoaderSource(string(importLiteral))), 0o644); err != nil {
-    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: write config loader: %w", err)
-  }
-  if err := writeConfigLoaderFile(tsconfig, []byte(typeScriptConfigLoaderTsconfig(loader, location, tempDir)), 0o644); err != nil {
-    return bannerLoadedConfig{}, fmt.Errorf("@ttsc/banner: write config loader tsconfig: %w", err)
-  }
 
   args := []string{
     "--project", tsconfig,
@@ -846,264 +626,68 @@ func loadBannerTypeScriptConfigFileWithInputs(location, resolutionRoot string) (
   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(`// @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;
+// prepareBannerTypeScriptConfigLoader owns the ordered preparation needed before
+// the loader process can start: dependency links, resolution recorder, generated
+// loader and tsconfig. Its caller supplies the invocation's filesystem operations
+// explicitly and retains directory lifetime ownership. The native caller supplies
+// linkNearestNodeModules and os.WriteFile; no mutable process-global hooks exist.
+//
+// A failed operation returns immediately with its original error context and
+// never admits the process with partial preparation. Each fixed file is written
+// once, native paths are joined through filepath, and helpers retain no state
+// across invocations. I/O failure decisions can be verified at this owner without
+// claiming that supplied callbacks establish actual kernel link capabilities.
+func prepareBannerTypeScriptConfigLoader(
+  tempDir, location string,
+  linkNodeModules func(string, string) error,
+  writeFile func(string, []byte, os.FileMode) error,
+) (string, string, error) {
+  if err := linkNodeModules(tempDir, filepath.Dir(location)); err != nil {
+    return "", "", err
   }
-}
 
-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;
+  loader := filepath.Join(tempDir, "loader.mts")
+  tsconfig := filepath.Join(tempDir, "tsconfig.json")
+  importSpecifier, err := relativeImportSpecifier(tempDir, location)
+  if err != nil {
+    return "", "", err
   }
-  if (Array.isArray(value)) {
-    for (const item of value) recordManifestTargets(item, directory, allowBare);
-    return;
+  importLiteral, _ := json.Marshal(importSpecifier)
+  recorder := filepath.Join(tempDir, "ttsc-resolution-inputs.cjs")
+  if err := writeFile(recorder, []byte(resolutioninputs.Recorder), 0o644); err != nil {
+    return "", "", fmt.Errorf("@ttsc/banner: write config loader: %w", err)
   }
-  if (value !== null && typeof value === "object") {
-    for (const item of Object.values(value)) recordManifestTargets(item, directory, allowBare);
+  recorderLiteral, _ := json.Marshal(recorder)
+  if err := writeFile(loader, []byte(bannerTypeScriptConfigLoaderSource(string(importLiteral), string(recorderLiteral))), 0o644); err != nil {
+    return "", "", fmt.Errorf("@ttsc/banner: write config loader: %w", err)
   }
-}
-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;
+  if err := writeFile(tsconfig, []byte(typeScriptConfigLoaderTsconfig(loader, location, tempDir)), 0o644); err != nil {
+    return "", "", fmt.Errorf("@ttsc/banner: write config loader tsconfig: %w", err)
   }
+
+  return loader, tsconfig, nil
 }
 
-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;
-  },
-});
+// 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.
+// recorderLiteral is the JSON-encoded path of the resolution input recorder
+// written beside the loader (resolutioninputs.Recorder).
+func bannerTypeScriptConfigLoaderSource(importLiteral, recorderLiteral string) string {
+  return fmt.Sprintf(`// @ts-nocheck
+import { createRequire } from "node:module";
 
-// 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;
-};
+// Which inputs a resolution read is the one rule ttsc owns
+// (resolutioninputs.Recorder), written beside this loader and required before
+// any hook is installed, so the recorder itself is no input.
+const recorderFile: string = %[2]s;
+const { createResolutionInputRecorder, observeResolutions } = createRequire(recorderFile)(recorderFile);
+const recorder = createResolutionInputRecorder({ extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json", ".node"] });
+
+// Every resolution the config makes is recorded: through a resolve hook, and
+// on a runtime whose require.resolve bypasses the hooks, through the one
+// entry point it reaches (resolutioninputs.Recorder, samchon/ttsc#1523).
+observeResolutions(recorder);
 
 declare const process: {
   exitCode?: number;
@@ -1119,15 +703,16 @@ declare const process: {
 // left for a trailing handler to settle.
 (async () => {
   try {
-    const importedConfig = await import(%s);
+    const importedConfig = await import(%[1]s);
     const value = await resolveConfig(importedConfig);
     const serializedValue = toSerializableBanner(value);
-    for (const input of [...inputs]) recordInput(input);
+    const recorded = recorder.finish();
     process.stdout.write(JSON.stringify({
       value: serializedValue,
-      hashes: Object.fromEntries(hashes),
-      inputs: [...inputs].sort(),
-      realpaths: Object.fromEntries(realpaths),
+      hashes: recorded.hashes,
+      complete: recorded.complete,
+      inputs: recorded.inputs,
+      realpaths: recorded.realpaths,
     }));
   } catch (error) {
     process.stderr.write(error instanceof Error && error.stack ? error.stack : String(error));
@@ -1181,7 +766,7 @@ function toSerializableBanner(value: unknown): unknown {
   }
   throw new Error("config file must export an object with a non-empty \"text\" string");
 }
-`, importLiteral)
+`, importLiteral, recorderLiteral)
 }
 
 // typeScriptConfigLoaderTsconfig returns the JSON content of a tsconfig that
@@ -1228,11 +813,8 @@ func typeScriptConfigLoaderTsconfig(loader, location, outDir string) string {
 // 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.
+// deliberately requires no in-tree ttsc module — so a change to one copy must
+// be made to all three.
 //
 // 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
@@ -1376,11 +958,11 @@ func realpathIfPossible(location string) string {
 // 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.
+// No automated check holds the three Go copies identical: a change lands in
+// all three by hand, and each package's own config-loader tests exercise it.
+// The JS original — `resolveConfigTsgo` / `resolveTtsxLauncher` in
+// packages/lint/src/index.ts — is a fourth copy in another language; 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
@@ -1579,13 +1161,6 @@ func nodePlatformPairFor(goos, goarch string) (string, string) {
   return platform, arch
 }
 
-// ttsxCommand builds an exec.Cmd that runs ttsx with the given args.
-// 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(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.
@@ -1691,8 +1266,8 @@ func relativeImportSpecifier(fromDir, location string) (string, error) {
   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.
+// setEnv updates env with key=value. If the key already exists its entry is
+// replaced in-place; otherwise the entry is appended to the returned slice.
 func setEnv(env []string, key, value string) []string {
   prefix := key + "="
   for i, entry := range env {