@ttsc/banner 0.13.1 → 0.14.0-dev.20260528.1

package/driver/banner.go

@@ -2,16 +2,24 @@ package banner
 
 import (
   "bytes"
+  "context"
   "encoding/json"
   "fmt"
   "os"
   "os/exec"
   "path/filepath"
+  "runtime"
   "strings"
+  "time"
 
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
+// configLoaderTimeout caps subprocesses that evaluate user-supplied banner
+// config files. This matches the strip/lint loaders so a hanging config does
+// not block the compiler indefinitely.
+const configLoaderTimeout = 60 * time.Second
+
 func init() {
   driver.RegisterPlugin(plugin{})
 }
@@ -296,8 +304,18 @@ const { pathToFileURL } = require("node:url");
 
 (async () => {
   const mod = await import(pathToFileURL(process.argv[1]).href);
-  const candidate = Object.prototype.hasOwnProperty.call(mod, "default") ? mod.default : mod;
-  const value = typeof candidate === "function" ? await candidate() : candidate;
+  let current = Object.prototype.hasOwnProperty.call(mod, "default") ? mod.default : mod;
+  for (let i = 0; i < 8; i++) {
+    if (current !== null && typeof current === "object" && typeof current.text === "string") {
+      break;
+    }
+    if (current !== null && typeof current === "object" && Object.prototype.hasOwnProperty.call(current, "default")) {
+      current = current.default;
+      continue;
+    }
+    break;
+  }
+  const value = typeof current === "function" ? await current() : current;
   process.stdout.write(JSON.stringify(toSerializableBanner(value)));
 })().catch((error) => {
   process.stderr.write(error && error.stack ? error.stack : String(error));
@@ -315,10 +333,15 @@ function toSerializableBanner(value) {
   if node == "" {
     node = "node"
   }
-  cmd := exec.Command(node, "-e", script, location)
+  ctx, cancel := context.WithTimeout(context.Background(), configLoaderTimeout)
+  defer cancel()
+  cmd := exec.CommandContext(ctx, node, "-e", script, location)
   cmd.Env = nodeConfigLoaderEnv(location)
   output, err := cmd.Output()
   if err != nil {
+    if ctx.Err() == context.DeadlineExceeded {
+      return nil, fmt.Errorf("@ttsc/banner: load config file %s: timed out after %s", location, configLoaderTimeout)
+    }
     stderr := ""
     if exit, ok := err.(*exec.ExitError); ok {
       stderr = strings.TrimSpace(string(exit.Stderr))
@@ -376,10 +399,15 @@ func loadBannerTypeScriptConfigFile(location string) (any, error) {
   }
   args = append(args, loader)
 
-  cmd := ttsxCommand(args...)
+  ctx, cancel := context.WithTimeout(context.Background(), configLoaderTimeout)
+  defer cancel()
+  cmd := ttsxCommandContext(ctx, args...)
   cmd.Env = nodeConfigLoaderEnv(location)
   output, err := cmd.Output()
   if err != nil {
+    if ctx.Err() == context.DeadlineExceeded {
+      return nil, fmt.Errorf("@ttsc/banner: load TypeScript config file %s: timed out after %s", location, configLoaderTimeout)
+    }
     stderr := ""
     if exit, ok := err.(*exec.ExitError); ok {
       stderr = strings.TrimSpace(string(exit.Stderr))
@@ -431,8 +459,11 @@ try {
 }
 
 async function resolveConfig(value: unknown): Promise<unknown> {
-  let current = value;
+  let current = isObject(value) && hasOwn(value, "default") ? value.default : value;
   for (let i = 0; i < 8; i++) {
+    if (isBannerObject(current)) {
+      break;
+    }
     if (isObject(current) && hasOwn(current, "default")) {
       current = current.default;
       continue;
@@ -449,6 +480,10 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object";
 }
 
+function isBannerObject(value: unknown): value is { text: string } {
+  return isObject(value) && typeof value.text === "string";
+}
+
 function hasOwn(value: Record<string, unknown>, key: string): boolean {
   return Object.prototype.hasOwnProperty.call(value, key);
 }
@@ -490,6 +525,11 @@ func typeScriptConfigLoaderTsconfig(loader, location, outDir string) string {
 // When TTSC_TTSX_BINARY has a script extension (.js, .ts, …) the binary is
 // invoked via the Node runtime so it is executed correctly on all platforms.
 func ttsxCommand(args ...string) *exec.Cmd {
+  return ttsxCommandContext(context.Background(), args...)
+}
+
+// ttsxCommandContext is the timeout-aware variant used by config loaders.
+func ttsxCommandContext(ctx context.Context, args ...string) *exec.Cmd {
   ttsx := os.Getenv("TTSC_TTSX_BINARY")
   if ttsx == "" {
     ttsx = "ttsx"
@@ -499,9 +539,9 @@ func ttsxCommand(args ...string) *exec.Cmd {
     if node == "" {
       node = "node"
     }
-    return exec.Command(node, append([]string{ttsx}, args...)...)
+    return exec.CommandContext(ctx, node, append([]string{ttsx}, args...)...)
   }
-  return exec.Command(ttsx, args...)
+  return exec.CommandContext(ctx, ttsx, args...)
 }
 
 // shouldRunTtsxThroughNode reports whether binary has a script file extension
@@ -541,8 +581,25 @@ func linkNearestNodeModules(tempDir, sourceDir string) error {
     return nil
   }
   link := filepath.Join(tempDir, "node_modules")
-  if err := os.Symlink(nodeModules, link); err != nil {
-    return fmt.Errorf("@ttsc/banner: link config node_modules %s: %w", nodeModules, err)
+  err := os.Symlink(nodeModules, link)
+  if err == nil {
+    return nil
+  }
+  if runtime.GOOS == "windows" {
+    jerr := createWindowsJunction(link, nodeModules)
+    if jerr == nil {
+      return nil
+    }
+    err = fmt.Errorf("%w (junction fallback: %v)", err, jerr)
+  }
+  return fmt.Errorf("@ttsc/banner: link config node_modules %s: %w", nodeModules, err)
+}
+
+// createWindowsJunction creates a directory junction on Windows.
+func createWindowsJunction(link, target string) error {
+  cmd := exec.Command("cmd", "/c", "mklink", "/J", link, target)
+  if out, err := cmd.CombinedOutput(); err != nil {
+    return fmt.Errorf("mklink /J failed: %v: %s", err, strings.TrimSpace(string(out)))
   }
   return nil
 }

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,0DAA6B;AAI7B,qDAAmC;AA4CnC;;;;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,sDAAsD;QACtD,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC;QAC/C,KAAK,EAAE,WAAW;KACnB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,0DAA6B;AAI7B,qDAAmC;AAyCnC;;;;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,sDAAsD;QACtD,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC;QAC/C,KAAK,EAAE,WAAW;KACnB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/banner",
-  "version": "0.13.1",
+  "version": "0.14.0-dev.20260528.1",
   "description": "First-party ttsc plugin that adds package-documentation JSDoc banners during emit.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -33,9 +33,9 @@
   ],
   "devDependencies": {
     "@types/node": "^25.3.0",
-    "@typescript/native-preview": "7.0.0-dev.20260522.1",
+    "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "rimraf": "^6.1.2",
-    "ttsc": "0.13.1"
+    "ttsc": "0.14.0-dev.20260528.1"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -7,9 +7,9 @@ export * from "./structures/index";
 /**
  * The shape returned by a ttsc plugin factory function.
  *
- * Mirrors the `driver.PluginDescriptor` contract in the Go host. The `source`
- * field points to the Go source directory that the host will compile into a
- * plugin binary (cached under `.ttsc/`).
+ * Mirrors the ttsc plugin descriptor contract. The `source` field points to the
+ * Go source directory that the host will compile and cache as either an
+ * executable sidecar or linked native source.
  */
 type TtscPluginDescriptor = {
   /** Human-readable plugin name used in logs and error messages. */
@@ -18,7 +18,7 @@ type TtscPluginDescriptor = {
   source: string;
   /**
    * Pipeline stage. `"transform"` plugins may rewrite source files; `"check"`
-   * plugins only produce diagnostics. Defaults to `"check"`.
+   * plugins only produce diagnostics. The framework default is `"transform"`.
    */
   stage?: "check" | "transform";
 };
@@ -31,10 +31,7 @@ type TtscPluginDescriptor = {
  * factories ignore it.
  */
 type TtscPluginFactoryContext<TConfig> = {
-  /**
-   * Absolute path to the compiled plugin binary (not yet built at factory
-   * time).
-   */
+  /** Absolute path to the selected ttsc native helper, not a plugin binary. */
   binary: string;
   /** Working directory of the ttsc invocation. */
   cwd: string;