ttsc 0.26.2 → 0.28.0

package/src/plugin/resolveCapabilityPlugins.ts

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { createNativeProjectContextJson } from "../compiler/internal/project/createNativeProjectContextArgs";
+import { resolveBinary } from "../compiler/internal/resolveBinary";
+import {
+  readCapabilityResolution,
+  writeCapabilityResolution,
+} from "./internal/capabilityResolutionCache";
+import { loadProjectPlugins } from "./internal/loadProjectPlugins";
+
+/**
+ * One plugin that declared the requested capability.
+ *
+ * `manifest` is the `--plugins-json` payload its sidecar needs to find its own
+ * configured entry. Without it the sidecar loads an empty rule configuration
+ * and answers as though the project declared nothing — an empty answer that
+ * looks exactly like a project which genuinely publishes none.
+ */
+export interface ITtscCapabilityPlugin {
+  binary: string;
+  manifest: string;
+  /**
+   * The `--project-context-json` payload, or `undefined` when the plugin's
+   * descriptor does not declare it wants one.
+   *
+   * A sidecar is handed a project root, not asked to derive one. Without this a
+   * rule that resolves its own inputs — the documents an evidence claim reads,
+   * a Prisma schema, an OpenAPI file — has no base to resolve them against, and
+   * answers with an empty set rather than an error, because "this project
+   * declares nothing" is a legitimate answer it cannot distinguish from "I was
+   * not told where the project is".
+   */
+  projectContext?: string;
+}
+
+/**
+ * The built sidecars of a project's configured plugins that declare one
+ * capability.
+ *
+ * This is the seam a consumer outside the compiler needs to ask a plugin a
+ * question the plugin declared it can answer. `ttscserver` already does this
+ * for `capabilities.lsp`, but it does it from inside the launcher; a separate
+ * tool — `@ttsc/graph`, an editor integration, a script — had no way to reach
+ * the same answer without reimplementing plugin discovery, descriptor
+ * evaluation, and the Go source build cache.
+ *
+ * It is contributor-agnostic by construction: the caller names a capability,
+ * not a package. A project that configures no plugin, or none declaring that
+ * capability, gets an empty array — which is an answer, not a failure, and is
+ * the common case.
+ *
+ * Building a plugin is not free the first time. The Go source build is cached
+ * by content, so a warm project pays a lookup; a cold one pays the build the
+ * next `ttsc` invocation would have paid anyway.
+ *
+ * @param options.capability - Capability flag the plugin descriptor must
+ *   declare.
+ * @param options.cwd - Project root. Defaults to the current directory.
+ * @param options.tsconfig - Project tsconfig path, relative to `cwd`.
+ * @returns One entry per declaring plugin, in configured plugin order.
+ */
+export function resolveCapabilityPlugins(options: {
+  capability: string;
+  cwd?: string;
+  tsconfig?: string;
+}): ITtscCapabilityPlugin[] {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const tsconfig = options.tsconfig ?? "tsconfig.json";
+  const cached = readCapabilityResolution({ cwd, tsconfig, version });
+  if (cached !== null) return select(cached, options.capability);
+
+  const binary = resolveBinary();
+  if (binary === null || binary === undefined) return [];
+  try {
+    const loaded = loadProjectPlugins({
+      binary,
+      cwd: options.cwd,
+      tsconfig: options.tsconfig,
+    });
+    // The manifest carries every configured plugin, not only the declaring one.
+    // A sidecar reads its OWN entry out of it — that entry is where its config
+    // file lives — and a manifest narrowed to the caller's capability would hand
+    // it a project it does not recognize, which is an empty answer rather than an
+    // error. This is the same string `runBuild` passes for a check-stage plugin.
+    const manifest = JSON.stringify(
+      loaded.nativePlugins.map((plugin) => ({
+        config: plugin.config,
+        name: plugin.name,
+        stage: plugin.stage,
+      })),
+    );
+    const wantsContext = loaded.nativePlugins.some(
+      (plugin) =>
+        (plugin.capabilities as Record<string, unknown> | undefined)
+          ?.projectContextArgs === true,
+    );
+    const answer = {
+      hostInputs: loaded.hostInputs,
+      manifest,
+      plugins: loaded.nativePlugins.map((plugin) => ({
+        binary: plugin.binary,
+        capabilities: Object.fromEntries(
+          Object.entries(
+            (plugin.capabilities as Record<string, unknown> | undefined) ?? {},
+          ).map(([name, declared]) => [name, declared === true] as const),
+        ),
+        source: plugin.source,
+      })),
+      projectContext: wantsContext
+        ? createNativeProjectContextJson(loaded.project)
+        : null,
+    };
+    writeCapabilityResolution({ cwd, tsconfig, version }, answer);
+    return select(answer, options.capability);
+  } catch {
+    // A project whose plugin configuration does not load is a project the user
+    // already sees an error for, from the command that compiles it. Failing here
+    // would turn "your lint config has a typo" into "the graph is broken", and
+    // the caller's own degraded answer is the honest one.
+    return [];
+  }
+}
+
+/** The declaring plugins, from a resolution however it was obtained. */
+function select(
+  resolution: {
+    manifest: string;
+    projectContext: string | null;
+    plugins: readonly {
+      binary: string;
+      capabilities: Record<string, boolean>;
+    }[];
+  },
+  capability: string,
+): ITtscCapabilityPlugin[] {
+  return resolution.plugins
+    .filter(
+      (plugin) =>
+        plugin.binary !== "" && plugin.capabilities[capability] === true,
+    )
+    .map((plugin) => ({
+      binary: plugin.binary,
+      manifest: resolution.manifest,
+      ...(plugin.capabilities.projectContextArgs === true &&
+      resolution.projectContext !== null
+        ? { projectContext: resolution.projectContext }
+        : {}),
+    }));
+}
+
+/**
+ * This build, as the resolution cache's key material.
+ *
+ * A ttsc upgrade can change what discovery finds — a new descriptor field, a
+ * different resolution order — so an entry written by another build is not this
+ * build's answer.
+ */
+const version = ((): string => {
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(
+        path.resolve(__dirname, "..", "..", "package.json"),
+        "utf8",
+      ),
+    ) as { version?: unknown };
+    return typeof manifest.version === "string" ? manifest.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();

package/src/register.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { prepareExecution } from "./launcher/internal/prepareExecution";
+import {
+  type RuntimeManifest,
+  installRuntimeHooks,
+} from "./launcher/internal/runtimeHooks";
+
+const cleanupDirectories = new Set<string>();
+let runtimeSequence = 0;
+
+/**
+ * Prepare one TypeScript root with the same checked compiler pipeline as ttsx,
+ * then expose its transient emit to the already-installed runtime hooks.
+ */
+function prepareEntry(filename: string): RuntimeManifest {
+  const execution = prepareExecution(filename, {
+    runtimeCacheKey: `register-${process.pid}-${++runtimeSequence}`,
+  });
+  cleanupDirectories.add(execution.cleanupDir);
+  return {
+    depCacheDir: path.join(execution.cleanupDir, "deps"),
+    emitDir: execution.emitDir,
+    emittedFiles: execution.emittedFiles,
+    entryFile: execution.entryFile,
+    entrySource: execution.entrySource,
+    moduleOptions: execution.moduleOptions,
+    projectRoot: execution.projectRoot,
+    rootDir: execution.rootDir,
+  };
+}
+
+/** Remove every register-owned transient emit when the JavaScript host exits. */
+function cleanupRuntimeOutputs(): void {
+  for (const directory of cleanupDirectories) {
+    try {
+      fs.rmSync(directory, { force: true, recursive: true });
+    } catch {
+      // Best effort: cleanup must not replace the host process exit status.
+    }
+  }
+  cleanupDirectories.clear();
+}
+
+process.once("exit", cleanupRuntimeOutputs);
+installRuntimeHooks({ prepareEntry });

package/src/structures/ITtscCompilerContext.ts

@@ -76,11 +76,14 @@ export interface ITtscCompilerContext {
   binary?: string;
 
   /**
-   * Additional environment variables for child compiler processes.
+   * Additional environment variables for child compiler and plugin-descriptor
+   * processes.
    *
    * Values are merged over `process.env` before ttsc starts TypeScript-Go,
-   * native plugin binaries, or the native compiler host used by
-   * {@link TtscCompiler.compile}.
+   * native plugin binaries, isolated descriptor evaluators (including the
+   * `ttsx` fallback), or the native compiler host used by
+   * {@link TtscCompiler.compile}. Descriptor output is diagnostic text and is
+   * forwarded to stderr so it cannot corrupt compiler/API protocol stdout.
    */
   env?: NodeJS.ProcessEnv;
 

package/src/structures/ITtscCompilerTransformation.ts

@@ -65,6 +65,17 @@ export namespace ITtscCompilerTransformation {
      * the same observation on the wire and after decoding.
      */
     candidates?: Record<string, string[]>;
+
+    /**
+     * SHA-256/null states returned by the compiler filesystem while this graph
+     * was being resolved, keyed in the same vocabulary as {@link edges}.
+     * Persistent hosts use them to reject a graph whose external file or
+     * superseding candidate changed during compilation.
+     */
+    inputHashes?: Record<string, string | null>;
+
+    /** Compiler-time physical identities paired with {@link inputHashes}. */
+    inputRealpaths?: Record<string, string | null>;
   }
 
   /** Successful source-to-source transformation result. */
@@ -122,6 +133,13 @@ export namespace ITtscCompilerTransformation {
      * declares completeness should stamp {@link graph} too; without it a listed
      * file retains no universal input at all.
      *
+     * Ttsc's own hosts stamp it for what they can prove: their source-to-source
+     * output is a syntactic re-print, so the built-in native host and the
+     * linked-plugin host list a file once every linked plugin able to
+     * contribute to it has declared its own contribution complete — which,
+     * where no plugin is active at all, is every file. An executable sidecar
+     * prints its own envelope and decides for itself.
+     *
      * Optional, and never required for correctness: an envelope without this
      * field keeps the sound host-owned bound. A file that is both listed here
      * and in {@link volatile} keeps the union, since the two claims contradict
@@ -140,6 +158,25 @@ export namespace ITtscCompilerTransformation {
      */
     graph?: IReferenceGraph;
 
+    /**
+     * Host-wide files consulted before the native transform starts, such as
+     * JavaScript plugin descriptors and explicitly selected plugin config
+     * files. Unlike {@link dependencies}, these affect every transformed file.
+     * Bundler adapters register and validate them as universal inputs without
+     * treating arbitrary unclassified project files as configuration.
+     */
+    hostInputs?: string[];
+
+    /**
+     * SHA-256 fingerprints captured by the plugin loader at the instant each
+     * host input influenced this generation. Internal cache validators use
+     * these to reject a result raced by a concurrent config/module change.
+     */
+    hostInputHashes?: Record<string, string | null>;
+
+    /** Evaluation-time physical identities paired with {@link hostInputs}. */
+    hostInputRealpaths?: Record<string, string | null>;
+
     /**
      * Transformed files (keyed like {@link typescript}) whose output depends on
      * non-file inputs (environment, time, network) as declared by the transform
@@ -188,6 +225,15 @@ export namespace ITtscCompilerTransformation {
      */
     graph?: IReferenceGraph;
 
+    /** Host-wide transform inputs; same contract as {@link ISuccess.hostInputs}. */
+    hostInputs?: string[];
+
+    /** Generation-time host-input fingerprints. */
+    hostInputHashes?: Record<string, string | null>;
+
+    /** Generation-time physical host-input identities. */
+    hostInputRealpaths?: Record<string, string | null>;
+
     /**
      * Volatile transformed files. Same shape and semantics as
      * {@link ISuccess.volatile}.

package/src/structures/ITtscPlugin.ts

@@ -22,6 +22,42 @@ export interface ITtscPlugin {
    */
   name?: string;
 
+  /**
+   * Absolute files whose contents or presence influence this descriptor or its
+   * native transform for every project file.
+   *
+   * Ttsc automatically records the descriptor's CommonJS module graph, tsconfig
+   * ancestry, package-discovery manifest, and an explicit `configFile`. Use
+   * this field for additional implicit config discovery and for files a native
+   * plugin reads outside the TypeScript reference graph. Missing paths are
+   * valid: they represent higher-priority discovery candidates whose later
+   * creation must invalidate a resident transform.
+   */
+  hostInputs?: string[];
+
+  /**
+   * Evaluation-time SHA-256 fingerprints for entries in {@link hostInputs}.
+   *
+   * Use a lowercase 64-digit digest for a file observed during descriptor
+   * evaluation and `null` for a missing candidate. Ttsc's generated resolution
+   * loaders also digest the stable kind marker for an existing directory
+   * candidate, so replacing that directory with a file invalidates the
+   * generation. The map is optional: ttsc still watches unhashed inputs, but
+   * persistent adapters conservatively decline narrow generation reuse because
+   * a later host snapshot cannot prove which state produced the descriptor.
+   */
+  hostInputHashes?: Record<string, string | null>;
+
+  /**
+   * Evaluation-time physical paths for entries in {@link hostInputs}.
+   *
+   * Use the canonical path returned by `fs.realpathSync.native`, or `null` when
+   * the input was missing. Persistent adapters pair this with
+   * {@link hostInputHashes} so retargeting a symlink or junction cannot attach
+   * output evaluated from one target to equal bytes at another target.
+   */
+  hostInputRealpaths?: Record<string, string | null>;
+
   /**
    * Go package directory, or a `go.mod` file, that ttsc lazily builds.
    *

package/tools/shim_audit/baseline.json

@@ -19,7 +19,6 @@
     "ESCAPE|checker|NodeBuilderContext",
     "ESCAPE|checker|ObjectType",
     "ESCAPE|checker|ReverseMappedType",
-    "ESCAPE|checker|SignatureFlags",
     "ESCAPE|checker|StringMappingType",
     "ESCAPE|checker|StructuredType",
     "ESCAPE|checker|SubstitutionType",
@@ -29,7 +28,6 @@
     "ESCAPE|checker|TupleType",
     "ESCAPE|checker|TypeFormatFlags",
     "ESCAPE|checker|TypeId",
-    "ESCAPE|checker|TypeMapper",
     "ESCAPE|checker|TypeParameter",
     "ESCAPE|checker|TypePredicate",
     "ESCAPE|checker|TypeReference",

package/utility/host.go

@@ -46,9 +46,18 @@ type hostOptions struct {
 // so cache layers can register every file whose content can influence a
 // transformed module without per-plugin reporting.
 type transformResult struct {
-  Diagnostics []any                  `json:"diagnostics,omitempty"`
-  TypeScript  map[string]string      `json:"typescript"`
-  Graph       *driver.TransformGraph `json:"graph,omitempty"`
+  // Dependencies and DependenciesComplete carry what the linked plugins
+  // declared about their own contribution to each file; the host prints the
+  // parsed AST syntactically, so it adds nothing of its own to either. See
+  // driver.Program.TransformDependenciesFor.
+  Dependencies         map[string][]string    `json:"dependencies,omitempty"`
+  DependenciesComplete []string               `json:"dependenciesComplete,omitempty"`
+  Diagnostics          []any                  `json:"diagnostics,omitempty"`
+  Graph                *driver.TransformGraph `json:"graph,omitempty"`
+  HostInputs           []string               `json:"hostInputs,omitempty"`
+  HostInputHashes      map[string]*string     `json:"hostInputHashes,omitempty"`
+  HostInputRealpaths   map[string]*string     `json:"hostInputRealpaths,omitempty"`
+  TypeScript           map[string]string      `json:"typescript"`
 }
 
 // RunCheck validates the project and linked plugin configuration without
@@ -150,6 +159,12 @@ func RunTransformWithIO(args []string, stdout, stderr io.Writer) int {
     text := shimprinter.EmitSourceFile(printer, file)
     out.TypeScript[apiOutputKey(opts.cwd, file.FileName())] = text
   }
+  dependencies := prog.TransformDependenciesFor(opts.cwd)
+  out.Dependencies = dependencies.Dependencies
+  out.DependenciesComplete = dependencies.Complete
+  out.HostInputs = prog.PluginHostInputs()
+  out.HostInputHashes = prog.PluginHostInputHashes()
+  out.HostInputRealpaths = prog.PluginHostInputRealpaths()
   data, _ := json.Marshal(out)
   fmt.Fprintln(opts.stdout, string(data))
   return 0

package/lib/internal/assertSafeExplicitCacheDirectory.d.ts

@@ -1,5 +0,0 @@
-/**
- * Refuse an explicit cache directory whose wholesale removal could delete the
- * project or an entire filesystem volume.
- */
-export declare function assertSafeExplicitCacheDirectory(projectRoot: string, cacheDirectory: string): void;

package/lib/internal/assertSafeExplicitCacheDirectory.js

@@ -1,26 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertSafeExplicitCacheDirectory = assertSafeExplicitCacheDirectory;
-const node_path_1 = __importDefault(require("node:path"));
-/**
- * Refuse an explicit cache directory whose wholesale removal could delete the
- * project or an entire filesystem volume.
- */
-function assertSafeExplicitCacheDirectory(projectRoot, cacheDirectory) {
-    const project = node_path_1.default.resolve(projectRoot);
-    const cache = node_path_1.default.resolve(cacheDirectory);
-    if (cache === node_path_1.default.parse(cache).root) {
-        throw new Error(`ttsc: refusing to clean cache directory ${JSON.stringify(cache)} because filesystem roots are never valid cache directories`);
-    }
-    const relative = node_path_1.default.relative(cache, project);
-    if (relative === "" ||
-        (relative !== ".." &&
-            !relative.startsWith(`..${node_path_1.default.sep}`) &&
-            !node_path_1.default.isAbsolute(relative))) {
-        throw new Error(`ttsc: refusing to clean cache directory ${JSON.stringify(cache)} because it equals or contains project root ${JSON.stringify(project)}; choose a dedicated cache directory`);
-    }
-}
-//# sourceMappingURL=assertSafeExplicitCacheDirectory.js.map

package/lib/internal/assertSafeExplicitCacheDirectory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"assertSafeExplicitCacheDirectory.js","sourceRoot":"","sources":["../../src/internal/assertSafeExplicitCacheDirectory.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B;;;GAGG;AACH,0CACE,WAAmB,EACnB,cAAsB;IAEtB,MAAM,OAAO,GAAG,mBAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,mBAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,mBAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,6DAA6D,CAC9H,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,mBAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,IACE,QAAQ,KAAK,EAAE;QACf,CAAC,QAAQ,KAAK,IAAI;YAChB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,mBAAI,CAAC,GAAG,EAAE,CAAC;YACrC,CAAC,mBAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAC7B,CAAC;QACD,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,+CAA+C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,sCAAsC,CAC7K,CAAC;IACJ,CAAC;AACH,CAAC"}

package/src/internal/assertSafeExplicitCacheDirectory.ts

@@ -1,29 +0,0 @@
-import path from "node:path";
-
-/**
- * Refuse an explicit cache directory whose wholesale removal could delete the
- * project or an entire filesystem volume.
- */
-export function assertSafeExplicitCacheDirectory(
-  projectRoot: string,
-  cacheDirectory: string,
-): void {
-  const project = path.resolve(projectRoot);
-  const cache = path.resolve(cacheDirectory);
-  if (cache === path.parse(cache).root) {
-    throw new Error(
-      `ttsc: refusing to clean cache directory ${JSON.stringify(cache)} because filesystem roots are never valid cache directories`,
-    );
-  }
-  const relative = path.relative(cache, project);
-  if (
-    relative === "" ||
-    (relative !== ".." &&
-      !relative.startsWith(`..${path.sep}`) &&
-      !path.isAbsolute(relative))
-  ) {
-    throw new Error(
-      `ttsc: refusing to clean cache directory ${JSON.stringify(cache)} because it equals or contains project root ${JSON.stringify(project)}; choose a dedicated cache directory`,
-    );
-  }
-}