@ttsc/banner 0.27.0 → 0.28.0

package/driver/banner.go

@@ -62,7 +62,18 @@ 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 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)
+  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.
@@ -151,7 +162,12 @@ func resolveBannerTextWithReporters(config map[string]any, cwd, tsconfigPath str
     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
   }
@@ -198,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.
@@ -434,7 +448,8 @@ func loadBannerScriptConfigFile(location string) (any, error) {
 
 func loadBannerScriptConfigFileWithInputs(location string) (bannerLoadedConfig, error) {
   const script = `
-const { createRequire, isBuiltin, registerHooks } = require("node:module");
+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");
@@ -630,6 +645,33 @@ registerHooks({
   },
 });
 
+// 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);
   let current = Object.prototype.hasOwnProperty.call(mod, "default") ? mod.default : mod;
@@ -809,11 +851,11 @@ func loadBannerTypeScriptConfigFileWithInputs(location, resolutionRoot string) (
 // JSON-encoded import specifier) and writes the serialized banner value to stdout.
 func bannerTypeScriptConfigLoaderSource(importLiteral string) string {
   return fmt.Sprintf(`// @ts-nocheck
-import { createRequire, isBuiltin, registerHooks } from "node:module";
+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 } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const inputs = new Set<string>();
 const hashes = new Map<string, string | null>();
@@ -1020,6 +1062,49 @@ registerHooks({
   },
 });
 
+// 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;
   stdout: { write(value: string, callback?: () => void): void };

package/package.json

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