@ttsc/paths 0.30.3 → 0.31.0

package/driver/paths.go

@@ -31,6 +31,77 @@ type plugin struct{}
 // declaration introduced (isModuleLoader). A complete declaration would have to
 // name those, and the second of them is exactly the global-scope set the
 // declaration drops, so silence keeps the sound host-owned bound (samchon/ttsc#1263).
+//
+// The rewriter uses the program's own Checker and filesystem case policy,
+// following TypeScript-Go's module-pattern precedence and emit-path model.
+// Its per-program source index and ordered patterns are reused by all file
+// walks; the AST traversal closure is allocated once per walk. Consumer names
+// do not select transforms, and native paths become slash-separated specifiers
+// only after output mapping.
+//
+// Principled implementation:
+//
+//  Program source membership and the Program's Checker determine eligible
+//  module references. Helpers commit to the compiler's best paths pattern,
+//  preserve its substitution order and map recognized source extensions to
+//  emitted extensions. Only eligible string literals change; global ambient
+//  module names and locally bound require calls retain their meaning. Failed
+//  source or output mapping leaves the specifier unchanged.
+//
+// Clear and simple design:
+//
+//  One rewriter owns the configuration snapshot and source index for this
+//  Program. Syntax eligibility, alias resolution and output mapping are
+//  separate helpers, so compiler path policy has one owner rather than a
+//  different implementation for each supported AST shape.
+//
+// Prohibited implementation shortcuts:
+//
+//  Pattern keys and substitution targets come from compiler options, and
+//  source membership comes from the Program. Extension constants represent
+//  emitted language formats; they do not identify consumers or expected
+//  outputs. Mutating owned AST string literals is the host's transform
+//  protocol, not replacement of foreign methods or runtime globals.
+//
+// Meaningful documentation:
+//
+//  Native comments explain why dependency completeness is withheld and how
+//  Checker facts delimit the rewrite. Helper documentation describes pattern
+//  precedence, source membership, root containment and extension semantics;
+//  member comments identify the stored configuration and source index. Each
+//  topic has its own paragraph, following the documentation skill.
+//
+// OS-neutral implementation:
+//
+//  Native paths use filepath operations, while normalized keys use the
+//  Program filesystem's actual case policy. Root containment compares those
+//  keys and keeps the original suffix spelling. Common-root inference uses
+//  TypeScript-Go path components and rejects disjoint volumes; only the
+//  final relative module specifier uses protocol forward slashes.
+//
+// Efficient algorithms:
+//
+//  Construction indexes S source paths and orders P patterns once. Traversal
+//  visits N AST nodes once, with one recursive closure per file. Each eligible
+//  literal scans at most P patterns, then the selected pattern's T targets;
+//  each target performs a fixed number of hash lookups for recognized source
+//  extensions and index names. Pattern precedence requires finding the best
+//  match; sorted first-match resolution avoids sorting at every literal.
+//  Source indexing avoids scanning S files for each candidate.
+//
+// Reuse equivalent work:
+//
+//  All file walks share the source index, ordered paths and Checker of the
+//  same Program. Their validity is restricted to that invocation's source
+//  membership, options and semantic snapshot. A later Program constructs a
+//  new rewriter; the plugin does not reuse results across changed snapshots.
+//
+// Bound retention and release resources:
+//
+//  This synchronous invocation owns the rewriter. It retains one source
+//  entry per Program file and copied configuration targets, plus the active
+//  traversal stack. No global cache, handle or background task survives the
+//  call; those references become reclaimable when ApplyProgram returns.
 func (plugin) ApplyProgram(prog *driver.Program, _ driver.PluginContext) error {
   rewriter := newRewriter(prog)
   for _, file := range prog.SourceFiles() {
@@ -42,20 +113,38 @@ func (plugin) ApplyProgram(prog *driver.Program, _ driver.PluginContext) error {
 // rewriter holds the resolved tsconfig paths configuration used to rewrite
 // module specifiers across an entire program.
 type rewriter struct {
-  checker           *shimchecker.Checker
-  basePath          string
+  // checker identifies module-loader bindings in the owning Program.
+  checker *shimchecker.Checker
+
+  // basePath anchors substitutions under the compiler's paths base.
+  basePath string
+
+  // canonicalFileName applies the Program filesystem's case policy.
   canonicalFileName func(string) string
-  jsxPreserve       bool
-  outDir            string
-  patterns          []pathPattern
-  rootDir           string
-  sourceFiles       map[string]string // canonical source path → original normalized path
+
+  // jsxPreserve selects .jsx output for JSX-family source files.
+  jsxPreserve bool
+
+  // outDir is the normalized destination directory; empty disables mapping.
+  outDir string
+
+  // patterns preserves substitution order within compiler-ranked patterns.
+  patterns []pathPattern
+
+  // rootDir anchors each source suffix placed beneath outDir.
+  rootDir string
+
+  // sourceFiles maps canonical source identities to original normalized names.
+  sourceFiles map[string]string
 }
 
 // pathPattern is a single tsconfig paths entry with its wildcard pattern and
 // ordered list of substitution targets.
 type pathPattern struct {
+  // pattern is an exact specifier or a pattern with at most one wildcard.
   pattern string
+
+  // targets contains substitution candidates in tsconfig declaration order.
   targets []string
 }
 
@@ -249,6 +338,9 @@ func (r *rewriter) rewrite(fromSource string, specifier string) (string, bool) {
 // order, with extension and index fallbacks. When none of them names a
 // program source the specifier stays unrewritten — falling through to a
 // weaker pattern would rewrite at a module the type checker never resolved.
+// Each target is combined with the paths base the way TypeScript-Go combines
+// it, so a rooted target, such as one a `${configDir}` template expanded to,
+// replaces the base instead of being appended to it.
 func (r *rewriter) resolveSource(specifier string) (string, bool) {
   for _, pattern := range r.patterns {
     star, ok := matchPattern(pattern.pattern, specifier)
@@ -257,7 +349,7 @@ func (r *rewriter) resolveSource(specifier string) (string, bool) {
     }
     for _, target := range pattern.targets {
       candidate := strings.Replace(target, "*", star, 1)
-      resolved := normalizePath(filepath.Join(r.basePath, candidate))
+      resolved := normalizePath(shimtspath.CombinePaths(normalizePath(r.basePath), candidate))
       if source, ok := r.lookupSource(resolved); ok {
         return source, true
       }
@@ -267,28 +359,60 @@ func (r *rewriter) resolveSource(specifier string) (string, bool) {
   return "", false
 }
 
-// lookupSource checks whether candidate (a normalized path, possibly without
-// extension) corresponds to a known source file. It tries the exact path, stem
-// with each known TypeScript/JavaScript source extension, and index files.
+// lookupSource checks whether candidate corresponds to a Program source that
+// can produce an output. Explicit module-format suffixes restrict replacement
+// to their own source family, as in TypeScript-Go's tryAddingExtensions, and an
+// unrecognized suffix such as `.service` is part of the file name, so source
+// extensions are appended to the whole candidate. The candidate itself is the
+// directory name for an index lookup; stripping its suffix there would search a
+// different directory.
 func (r *rewriter) lookupSource(candidate string) (string, bool) {
   normalized := normalizePath(candidate)
   if source, ok := r.sourceFiles[r.sourceKey(normalized)]; ok {
+    if isDeclarationSource(source) {
+      return "", false
+    }
     return source, true
   }
   stem := stripKnownSourceExtension(normalized)
-  for _, ext := range sourceLookupExtensions {
+  extensions := sourceLookupExtensions
+  switch strings.ToLower(filepath.Ext(normalized)) {
+  case ".mjs", ".mts":
+    extensions = []string{".mts", ".mjs"}
+  case ".cjs", ".cts":
+    extensions = []string{".cts", ".cjs"}
+  case ".jsx", ".tsx":
+    extensions = []string{".tsx", ".ts", ".jsx", ".js"}
+  case ".js", ".ts":
+    extensions = []string{".ts", ".tsx", ".js", ".jsx"}
+  case "":
+  default:
+    // An unrecognized suffix belongs to the file name, as in `./user.service`:
+    // tsc appends the source extensions to the whole candidate, so the stem
+    // must keep the suffix that recognized extensions lose.
+    stem = normalized
+  }
+  for _, ext := range extensions {
     if source, ok := r.sourceFiles[r.sourceKey(stem+ext)]; ok {
       return source, true
     }
   }
   for _, ext := range sourceLookupExtensions {
-    if source, ok := r.sourceFiles[r.sourceKey(filepath.Join(stem, "index"+ext))]; ok {
+    if source, ok := r.sourceFiles[r.sourceKey(filepath.Join(normalized, "index"+ext))]; ok {
       return source, true
     }
   }
   return "", false
 }
 
+// isDeclarationSource reports inputs that type-check but emit no target file.
+func isDeclarationSource(source string) bool {
+  lower := strings.ToLower(source)
+  return strings.HasSuffix(lower, ".d.ts") ||
+    strings.HasSuffix(lower, ".d.mts") ||
+    strings.HasSuffix(lower, ".d.cts")
+}
+
 // sourceKey applies the compiler host's filesystem identity rule to one path.
 // Synthetic test rewriters leave canonicalFileName nil and retain the previous
 // exact-key behavior.
@@ -307,13 +431,34 @@ func (r *rewriter) outputPathForSource(source string) string {
   if r.outDir == "" || r.rootDir == "" {
     return ""
   }
-  rel, err := filepath.Rel(r.rootDir, source)
-  if err != nil || isOutsideRelativePath(rel) {
+  rel, ok := r.pathBelowRootDir(source)
+  if !ok {
     return ""
   }
   return normalizePath(filepath.Join(r.outDir, replaceSourceExtension(rel, emittedExtension(rel, r.jsxPreserve))))
 }
 
+// pathBelowRootDir returns source's path below rootDir, decided the way
+// TypeScript-Go places an output under outDir
+// (`outputpaths.GetSourceFilePathInNewDir`): rootDir contains source by the
+// compiler host's case rule, and the rest keeps the source's own spelling. A
+// Program can spell a file the way a paths target named it, such as
+// `SRC/DIRECTORY/index.ts` below `src`, so an operating system's own path
+// comparison, case-sensitive on POSIX even on a case-insensitive volume, would
+// place it outside rootDir.
+func (r *rewriter) pathBelowRootDir(source string) (string, bool) {
+  root := normalizePath(r.rootDir)
+  if !strings.HasSuffix(root, "/") {
+    root += "/"
+  }
+  file := normalizePath(source)
+  if len(file) <= len(root) || file[len(root)-1] != '/' ||
+    r.sourceKey(file[:len(root)]) != r.sourceKey(root) {
+    return "", false
+  }
+  return file[len(root):], true
+}
+
 // emittedExtension returns the output-file extension that TypeScript-Go writes
 // for a given Program source. TypeScript/JavaScript-family sources are
 // transpiled to the matching JavaScript runtime extension. Non-transpiled
@@ -410,6 +555,11 @@ func optionalPath(value string, cwd string) string {
 // every input file. The rewriter must anchor output paths exactly where tsgo
 // anchors its own emit, or the rewritten specifiers drift from the real
 // output layout.
+//
+// A tsconfig-loaded Program always carries its config path, so the shared
+// directory fallback serves only a Program built without one. That fallback
+// intersects every file name it is given, whereas TypeScript-Go excludes
+// declaration files; the caller passes the Program's full source list.
 func inferredRootDir(configFilePath string, fileNames []string, currentDirectory string, useCaseSensitiveFileNames bool) string {
   if configFilePath != "" {
     return normalizePath(filepath.Dir(configFilePath))
@@ -481,9 +631,3 @@ func stripKnownSourceExtension(value string) string {
 func replaceSourceExtension(value string, ext string) string {
   return stripKnownSourceExtension(filepath.ToSlash(value)) + ext
 }
-
-// isOutsideRelativePath reports whether a relative path escapes its base
-// directory (i.e. starts with "..").
-func isOutsideRelativePath(rel string) bool {
-  return rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator))
-}

package/go.mod

@@ -5,11 +5,11 @@ go 1.26
 require github.com/samchon/ttsc/packages/ttsc v0.0.0
 
 require (
-	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
-	github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157 // indirect
+	github.com/microsoft/typescript-go v0.0.0-20260610182825-7fc57c005063 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
-	golang.org/x/text v0.35.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
 )

package/lib/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Locate the native paths transform for the ttsc plugin host.
+ *
+ * The host supplies this module's absolute directory in `context.dirname`. The
+ * descriptor points to the sibling Go driver; compiler options and source
+ * rewriting are consumed by that driver rather than evaluated by this factory.
+ *
+ * The factory reads no external config file. Its empty host-input hashes let
+ * the host reuse descriptor evaluation under the observed module graph without
+ * claiming that the native transform has no project-wide dependencies.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The host evaluates the default-export factory with the loaded module's
+ *   absolute directory. Resolving its sibling driver directory identifies the
+ *   shipped Go transform independently of the caller's working directory.
+ *   The descriptor registers that source at the host's transform stage;
+ *   compiler options and alias resolution remain the native driver's inputs.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This factory only maps the host directory to a native registration. Its
+ *   context type exposes that one input, and its result type separates source,
+ *   package identity, stage and the declaration of external descriptor inputs.
+ *   It has no duplicate alias policy or speculative plugin configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The package name and stage are protocol values; no consumer, fixture or
+ *   test determines them, and the factory patches no foreign API.
+ *
+ *   The default-export protocol uses the supported host loader. No wrapper
+ *   substitutes its own transform implementation or compensates for failed
+ *   source resolution.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the host directory, driver ownership and the
+ *   limited meaning of descriptor-input reuse in separate paragraphs. Context
+ *   and result members describe their consuming protocol rather than
+ *   repeating their types, following the documentation skill's clear prose
+ *   and rationale guidance. The README explains the compiler options that
+ *   control the separate native transformation.
+ */
+export default function createTtscPaths(context: TtscPathsFactoryContext): TtscPathsDescriptor;
+/** The part of the host factory context this descriptor reads. */
+type TtscPathsFactoryContext = {
+    /** Absolute directory of the loaded descriptor module in every load mode. */
+    dirname: string;
+};
+/** Native transform registration returned to the ttsc plugin host. */
+type TtscPathsDescriptor = {
+    /** The bundled driver host records actual writes and their physical sources. */
+    capabilities: {
+        emitProvenance: true;
+    };
+    /** No external files are read while this factory constructs its descriptor. */
+    hostInputHashes: Record<string, string | null>;
+    /** Package identity used for diagnostics and plugin registration. */
+    name: string;
+    /** Absolute Go source directory compiled and linked by the host. */
+    source: string;
+    /** Register source rewriting in the transform stage. */
+    stage: "transform";
+};
+export {};

package/lib/index.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createTtscPaths;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Locate the native paths transform for the ttsc plugin host.
+ *
+ * The host supplies this module's absolute directory in `context.dirname`. The
+ * descriptor points to the sibling Go driver; compiler options and source
+ * rewriting are consumed by that driver rather than evaluated by this factory.
+ *
+ * The factory reads no external config file. Its empty host-input hashes let
+ * the host reuse descriptor evaluation under the observed module graph without
+ * claiming that the native transform has no project-wide dependencies.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The host evaluates the default-export factory with the loaded module's
+ *   absolute directory. Resolving its sibling driver directory identifies the
+ *   shipped Go transform independently of the caller's working directory.
+ *   The descriptor registers that source at the host's transform stage;
+ *   compiler options and alias resolution remain the native driver's inputs.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This factory only maps the host directory to a native registration. Its
+ *   context type exposes that one input, and its result type separates source,
+ *   package identity, stage and the declaration of external descriptor inputs.
+ *   It has no duplicate alias policy or speculative plugin configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The package name and stage are protocol values; no consumer, fixture or
+ *   test determines them, and the factory patches no foreign API.
+ *
+ *   The default-export protocol uses the supported host loader. No wrapper
+ *   substitutes its own transform implementation or compensates for failed
+ *   source resolution.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the host directory, driver ownership and the
+ *   limited meaning of descriptor-input reuse in separate paragraphs. Context
+ *   and result members describe their consuming protocol rather than
+ *   repeating their types, following the documentation skill's clear prose
+ *   and rationale guidance. The README explains the compiler options that
+ *   control the separate native transformation.
+ */
+function createTtscPaths(context) {
+    return {
+        capabilities: { emitProvenance: true },
+        // The descriptor reads no file outside its module graph, which lets a
+        // launch reuse its evaluation (samchon/ttsc#1561).
+        hostInputHashes: {},
+        name: "@ttsc/paths",
+        // The host supplies the descriptor's directory for every load mode.
+        source: node_path_1.default.resolve(context.dirname, "..", "driver"),
+        stage: "transform",
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,yBACE,OAAgC;IAEhC,OAAO;QACL,YAAY,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE;QACtC,sEAAsE;QACtE,mDAAmD;QACnD,eAAe,EAAE,EAAE;QACnB,IAAI,EAAE,aAAa;QACnB,oEAAoE;QACpE,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC;QACrD,KAAK,EAAE,WAAW;KACnB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@ttsc/paths",
-  "version": "0.30.3",
+  "version": "0.31.0",
   "description": "First-party ttsc plugin that rewrites emitted module specifiers from tsconfig paths.",
-  "main": "src/index.cjs",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "exports": {
-    ".": "./src/index.cjs",
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [
@@ -21,11 +25,18 @@
   "files": [
     "README.md",
     "driver/paths.go",
-    "src/index.cjs",
+    "lib",
+    "src",
     "go.mod",
     "plugin/main.go",
     "plugin/paths.go"
   ],
+  "devDependencies": {
+    "@wrtnlabs/evidence": "^0.3.1",
+    "@types/node": "^25.3.0",
+    "rimraf": "^6.1.2",
+    "typescript": "^7.0.2"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/samchon/ttsc"
@@ -35,5 +46,9 @@
   "bugs": {
     "url": "https://github.com/samchon/ttsc/issues"
   },
-  "homepage": "https://ttsc.dev"
+  "homepage": "https://ttsc.dev",
+  "scripts": {
+    "build": "rimraf lib && tsc",
+    "evidence": "evidence"
+  }
 }

package/plugin/main.go

@@ -2,7 +2,6 @@
 package main
 
 import (
-  "fmt"
   "os"
 
   "github.com/samchon/ttsc/packages/ttsc/utility"
@@ -10,27 +9,28 @@ import (
 
 const version = "0.0.1"
 
+// main exits the standalone process with its command dispatch status.
+//
+// These review grounds cover this private operation and its actual callees.
+// Go Evidence does not admit private declaration acknowledgment tags.
+//
+// Common: Principled implementation: os.Args excludes the executable name and os.Exit propagates the actual run status to the process consumer.
+// Common: Clear and simple design: The entrypoint binds process lifetime while run owns identity and stream delegation.
+// Common: Prohibited implementation shortcuts: The process uses the real command return status without rewriting failures or bypassing package registration.
+// Common: Meaningful documentation: The native comment names process status propagation separately from these native review grounds.
+// Portability: OS-neutral implementation: Go's os package supplies native argv and process exit semantics without host-specific command quoting.
 func main() {
   os.Exit(run(os.Args[1:]))
 }
 
+// run supplies this standalone plugin's identity and process streams to the
+// shared production utility dispatch; linked registration remains in init.
+//
+// Common: Principled implementation: The package identity and unchanged version constant reach the shared actual command owner with original argv and process writers.
+// Common: Clear and simple design: One delegation leaves command semantics with utility.RunCommandWithIO and package registration with the sibling init import.
+// Common: Prohibited implementation shortcuts: Production execution uses the same dispatch as direct units and retains the real host for build, transform and check.
+// Common: Meaningful documentation: Native prose identifies identity, process stream binding and unchanged linked registration separately from these native review grounds.
+// Portability: OS-neutral implementation: os supplies the native process streams and argv values without a shell or path reconstruction.
 func run(args []string) int {
-  if len(args) == 0 {
-    fmt.Fprintln(os.Stderr, "@ttsc/paths: command required (expected build|transform|check|version)")
-    return 2
-  }
-  switch args[0] {
-  case "-v", "--version", "version":
-    fmt.Fprintf(os.Stdout, "@ttsc/paths %s\n", version)
-    return 0
-  case "build":
-    return utility.RunBuild(args[1:])
-  case "transform":
-    return utility.RunTransform(args[1:])
-  case "check":
-    return utility.RunCheck(args[1:])
-  default:
-    fmt.Fprintf(os.Stderr, "@ttsc/paths: unknown command %q\n", args[0])
-    return 2
-  }
+  return utility.RunCommandWithIO("@ttsc/paths", version, args, os.Stdout, os.Stderr)
 }

package/src/index.ts

@@ -0,0 +1,77 @@
+import path from "node:path";
+
+/**
+ * Locate the native paths transform for the ttsc plugin host.
+ *
+ * The host supplies this module's absolute directory in `context.dirname`. The
+ * descriptor points to the sibling Go driver; compiler options and source
+ * rewriting are consumed by that driver rather than evaluated by this factory.
+ *
+ * The factory reads no external config file. Its empty host-input hashes let
+ * the host reuse descriptor evaluation under the observed module graph without
+ * claiming that the native transform has no project-wide dependencies.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The host evaluates the default-export factory with the loaded module's
+ *   absolute directory. Resolving its sibling driver directory identifies the
+ *   shipped Go transform independently of the caller's working directory.
+ *   The descriptor registers that source at the host's transform stage;
+ *   compiler options and alias resolution remain the native driver's inputs.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This factory only maps the host directory to a native registration. Its
+ *   context type exposes that one input, and its result type separates source,
+ *   package identity, stage and the declaration of external descriptor inputs.
+ *   It has no duplicate alias policy or speculative plugin configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The package name and stage are protocol values; no consumer, fixture or
+ *   test determines them, and the factory patches no foreign API.
+ *
+ *   The default-export protocol uses the supported host loader. No wrapper
+ *   substitutes its own transform implementation or compensates for failed
+ *   source resolution.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc explains the host directory, driver ownership and the
+ *   limited meaning of descriptor-input reuse in separate paragraphs. Context
+ *   and result members describe their consuming protocol rather than
+ *   repeating their types, following the documentation skill's clear prose
+ *   and rationale guidance. The README explains the compiler options that
+ *   control the separate native transformation.
+ */
+export default function createTtscPaths(
+  context: TtscPathsFactoryContext,
+): TtscPathsDescriptor {
+  return {
+    capabilities: { emitProvenance: true },
+    // The descriptor reads no file outside its module graph, which lets a
+    // launch reuse its evaluation (samchon/ttsc#1561).
+    hostInputHashes: {},
+    name: "@ttsc/paths",
+    // The host supplies the descriptor's directory for every load mode.
+    source: path.resolve(context.dirname, "..", "driver"),
+    stage: "transform",
+  };
+}
+
+/** The part of the host factory context this descriptor reads. */
+type TtscPathsFactoryContext = {
+  /** Absolute directory of the loaded descriptor module in every load mode. */
+  dirname: string;
+};
+
+/** Native transform registration returned to the ttsc plugin host. */
+type TtscPathsDescriptor = {
+  /** The bundled driver host records actual writes and their physical sources. */
+  capabilities: { emitProvenance: true };
+
+  /** No external files are read while this factory constructs its descriptor. */
+  hostInputHashes: Record<string, string | null>;
+
+  /** Package identity used for diagnostics and plugin registration. */
+  name: string;
+
+  /** Absolute Go source directory compiled and linked by the host. */
+  source: string;
+
+  /** Register source rewriting in the transform stage. */
+  stage: "transform";
+};

package/src/index.cjs

@@ -1,14 +0,0 @@
-// @ts-check
-"use strict";
-
-const path = require("node:path");
-
-module.exports = function createTtscPaths(context) {
-  return {
-    name: "@ttsc/paths",
-    // `context.dirname` is this descriptor's own directory in every load mode —
-    // the ESM-safe replacement for `__dirname`.
-    source: path.resolve(context.dirname, "..", "driver"),
-    stage: "transform",
-  };
-};