ttsc 0.12.3 → 0.12.4

package/src/plugin/internal/loadProjectPlugins.ts

@@ -2,9 +2,10 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
+import { findNearestGoMod } from "../../compiler/internal/paths";
 import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
-import type { ITtscPluginContributor } from "../../structures/ITtscPluginContributor";
 import type { ITtscPlugin } from "../../structures/ITtscPlugin";
+import type { ITtscPluginContributor } from "../../structures/ITtscPluginContributor";
 import type { ITtscPluginFactoryContext } from "../../structures/ITtscPluginFactoryContext";
 import type { ITtscProjectPluginConfig } from "../../structures/ITtscProjectPluginConfig";
 import type { TtscPluginStage } from "../../structures/TtscPluginStage";
@@ -30,6 +31,24 @@ type PackageManifest = {
   ttsc?: unknown;
 };
 
+/**
+ * Resolve, load, and build all native plugin sidecars for a TypeScript project.
+ *
+ * Reads the project config, discovers plugin entries (from tsconfig and package
+ * auto-discovery), validates and composes their descriptors, then invokes
+ * `buildSourcePlugin` to compile each Go source package into a cached binary.
+ * Returns the ordered set of loaded native plugins alongside the parsed project
+ * config.
+ *
+ * @param options.binary - Absolute path to the ttsc native helper binary.
+ * @param options.cacheDir - Override the plugin binary cache directory.
+ * @param options.cwd - Working directory for resolving relative paths.
+ * @param options.entries - Explicit plugin entries; `false` disables all
+ *   plugins (skips both tsconfig entries and package auto-discovery).
+ * @param options.file - Path to the tsconfig/jsconfig file.
+ * @param options.projectRoot - Override the project root directory.
+ * @param options.tsconfig - Alias for `file`.
+ */
 export function loadProjectPlugins(options: {
   binary: string;
   cacheDir?: string;
@@ -85,14 +104,21 @@ export function loadProjectPlugins(options: {
     validatePluginSource(plugin);
     const contributors = validatePluginContributors(plugin);
     const source = resolvePluginSource(plugin.source, context.projectRoot);
-    const kind = resolveNativeSourceKind(source, plugin, entries[index]!.config, index);
+    const kind = resolveNativeSourceKind(
+      source,
+      plugin,
+      entries[index]!.config,
+      index,
+    );
     if (kind === "linked" && stage !== "transform") {
       throw new Error(
         `ttsc: plugin "${pluginLabel(plugin, entries[index]!.config, index)}" source is a linked Go package, but only transform-stage plugins can be linked into a compiler host`,
       );
     }
     const linkedContributorName =
-      kind === "linked" ? `linked_${String(index).padStart(6, "0")}` : undefined;
+      kind === "linked"
+        ? `linked_${String(index).padStart(6, "0")}`
+        : undefined;
     return {
       contributors,
       config: entries[index]!.config,
@@ -261,6 +287,7 @@ function composePluginSources(
     return {
       ...plugin,
       source: aggregate.plugin.source,
+      contributors: aggregate.plugin.contributors,
     };
   });
 }
@@ -276,6 +303,14 @@ function matchesPluginAlias(
   );
 }
 
+/**
+ * Return `true` when the project has at least one enabled plugin entry.
+ *
+ * Used by callers that need to skip plugin-specific work when no plugins are
+ * configured, without paying the full cost of `loadProjectPlugins`.
+ *
+ * @param entries - Explicit entries; `false` always returns `false`.
+ */
 export function hasProjectPluginEntries(
   project: ITtscParsedProjectConfig,
   entries?: readonly ITtscProjectPluginConfig[] | false,
@@ -610,7 +645,10 @@ function resolveNativeSourceKind(
   config: ITtscProjectPluginConfig,
   index: number,
 ): "executable" | "linked" {
-  const packageDir = resolveGoPackageDir(source, pluginLabel(plugin, config, index));
+  const packageDir = resolveGoPackageDir(
+    source,
+    pluginLabel(plugin, config, index),
+  );
   if (findNearestGoMod(packageDir, GO_MOD_SEARCH_MAX_DEPTH) === null) {
     throw new Error(
       `ttsc: plugin "${pluginLabel(plugin, config, index)}" source must be inside a Go module with go.mod within ${GO_MOD_SEARCH_MAX_DEPTH} parent directories: ${source}`,
@@ -625,20 +663,6 @@ function resolveNativeSourceKind(
   return packageName === "main" ? "executable" : "linked";
 }
 
-function findNearestGoMod(from: string, maxDepth: number): string | null {
-  let current = path.resolve(from);
-  let depth = 0;
-  while (true) {
-    const candidate = path.join(current, "go.mod");
-    if (fs.existsSync(candidate)) return candidate;
-    if (depth >= maxDepth) return null;
-    const parent = path.dirname(current);
-    if (parent === current) return null;
-    current = parent;
-    depth += 1;
-  }
-}
-
 function resolveGoPackageDir(source: string, label: string): string {
   if (!fs.existsSync(source)) {
     throw new Error(`ttsc: plugin "${label}" source does not exist: ${source}`);

package/src/structures/ITtscCompilerTransformation.ts

@@ -22,7 +22,14 @@ export namespace ITtscCompilerTransformation {
     /** Non-fatal diagnostics reported during transformation. */
     diagnostics?: ITtscCompilerDiagnostic[];
 
-    /** Transformed TypeScript source text keyed by project file path. */
+    /**
+     * Transformed TypeScript source text keyed by project-relative file path.
+     *
+     * Values are TypeScript source text, never JavaScript, declaration files,
+     * or source maps. When no transform sidecar is configured, this map
+     * contains the unmodified TypeScript files loaded by the TypeScript-Go
+     * Program.
+     */
     typescript: Record<string, string>;
   }
 
@@ -31,7 +38,13 @@ export namespace ITtscCompilerTransformation {
     /** Indicates that transformation completed with diagnostics. */
     type: "failure";
 
-    /** Transformed or partially transformed TypeScript source text. */
+    /**
+     * Transformed or partially transformed TypeScript source text keyed by
+     * project-relative file path.
+     *
+     * May be empty or partial when diagnostics prevented the transform sidecar
+     * from completing its pass.
+     */
     typescript: Record<string, string>;
 
     /** Diagnostics reported during transformation. */

package/src/structures/ITtscPlugin.ts

@@ -96,5 +96,4 @@ export interface ITtscPlugin {
    *   unique within a single plugin build.
    */
   contributors?: ITtscPluginContributor[];
-
 }

package/src/structures/internal/TtscSingleFileEmitOptions.ts

@@ -10,6 +10,4 @@ export interface TtscSingleFileEmitOptions extends TtscCommonOptions {
   out?: string;
   /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
   quiet?: boolean;
-  /** Normalize compiler output so diagnostics can be parsed structurally. */
-  structuredDiagnostics?: boolean;
 }

package/tools/gen_shims/main.go

@@ -56,13 +56,28 @@ var packagesToShim = []string{
   "vfs/osvfs",
 }
 
+// ExtraShim is the schema for the per-shim-directory `extra-shim.json` file.
+// It lets maintainers extend the generated output beyond what gen_shims can
+// derive automatically from the public API surface.
 type ExtraShim struct {
-  ExtraFunctions  []string
-  ExtraMethods    map[string][]string
-  ExtraFields     map[string][]string
+  // ExtraFunctions lists unexported function names that should be shimmed via
+  // go:linkname in addition to the exported ones gen_shims discovers itself.
+  ExtraFunctions []string
+  // ExtraMethods maps type name → method names for unexported or
+  // otherwise-unlinkable methods that should be forwarded.
+  ExtraMethods map[string][]string
+  // ExtraFields maps type name → field names whose values should be exposed
+  // through unsafe pointer casts (used when go:linkname cannot reach them).
+  ExtraFields map[string][]string
+  // IgnoreFunctions lists exported function names that gen_shims should skip
+  // entirely, typically because the caller supplies a hand-written alternative.
   IgnoreFunctions []string
 }
 
+// signatureHasUnexportedType reports whether any parameter of the function
+// signature refers to an unexported named type (optionally through a pointer).
+// Such functions cannot be linked safely because the shim package cannot
+// reference the unexported type by name.
 func signatureHasUnexportedType(t types.Signature) bool {
   if params := t.Params(); params != nil {
     for v := range params.Variables() {
@@ -128,6 +143,9 @@ func main() {
       extraShim.IgnoreFunctions = []string{}
     }
 
+    // importedPackages tracks every package import the generated file needs.
+    // true  = referenced by name (needs a named import).
+    // false = only needed for its side-effects (blank import "_").
     importedPackages := map[string]bool{}
     importPackage := func(path string, directly bool) {
       if directly {
@@ -137,12 +155,21 @@ func main() {
       }
     }
 
+    // qualifierOnlyPackageName records a direct import for every package the
+    // type-string references and returns just the package short name, producing
+    // output like `ast.Node` instead of a full path.
     var qualifierOnlyPackageName types.Qualifier = func(p *types.Package) string {
       importPackage(p.Path(), true)
       return p.Name()
     }
+    // qualifierEmptyPackageName omits the package qualifier entirely; used when
+    // writing the receiver type inside a go:linkname directive where the package
+    // prefix must not appear.
     var qualifierEmptyPackageName types.Qualifier = func(p *types.Package) string { return "" }
 
+    // emitGoLinknameDirective appends a `//go:linkname localName pkg.Func`
+    // pragma line to shimBuilder, registering unsafe and the source package as
+    // blank imports so the linker can resolve the symbol.
     emitGoLinknameDirective := func(localName string, fn *types.Func) {
       importPackage("unsafe", false)
       importPackage(pkg.Types.Path(), false)
@@ -161,6 +188,9 @@ func main() {
       shimBuilder.WriteByte('\n')
     }
 
+    // emitLinkedFunction emits a go:linkname directive and a matching func
+    // declaration for fn. Generic functions (TypeParams != nil) and functions
+    // with unexported parameter types are skipped (returns false).
     emitLinkedFunction := func(fn *types.Func) bool {
       if fn.Signature().TypeParams() != nil {
         return false
@@ -221,10 +251,9 @@ func main() {
         shimBuilder.WriteString("\n")
       }
 
-      switch object.(type) {
+      switch typedObj := object.(type) {
       case *types.TypeName:
-        typeName := object.(*types.TypeName)
-        t := typeName.Type()
+        t := typedObj.Type()
         named, isNamed := t.(*types.Named)
         if isNamed {
           _, nameWithTypeParams, _ := strings.Cut(types.TypeString(named, qualifierOnlyPackageName), ".")
@@ -297,6 +326,10 @@ func main() {
           matchedExtraFields[name] = true
           mirrorStructName := "extra_" + name
 
+          // emitExtraStruct emits a mirror struct (`extra_<Name>`) whose field
+          // layout matches the unexported original so that unsafe.Pointer casts
+          // in the generated accessor functions are safe. Unexported pointer
+          // fields whose element type is also unexported are recursively mirrored.
           var emitExtraStruct func(name string, s *types.Struct)
           emitExtraStruct = func(name string, s *types.Struct) {
             shimBuilder.WriteString("type extra_")
@@ -384,12 +417,14 @@ func main() {
         printReexport("var")
       case *types.Func:
         if !slices.Contains(extraShim.IgnoreFunctions, name) {
-          funcType := object.(*types.Func)
-          emitLinkedFunction(funcType)
+          emitLinkedFunction(typedObj)
         }
       }
     }
 
+    // Verify that every extra function/method requested in extra-shim.json was
+    // actually found in the package. A missing symbol means the json file is
+    // stale relative to the upstream typescript-go API.
     exit := false
     for fnName, found := range matchedExtraFunctions {
       if found {