ttsc 0.10.2 → 0.11.0-dev.20260517

package/src/compiler/internal/runBuild.ts

@@ -106,6 +106,21 @@ export function runBuild(
     }
 
     if (options.emit === false) {
+      if (options.format === true) {
+        // Format mode is write-only by contract: the lint sidecar
+        // already rewrote source files and reported nothing. Running
+        // tsgo --noEmit OR a transform compiler afterwards would either
+        // surface unrelated type errors as if they were format failures
+        // (tsgo path) or apply transform-stage rewrites on top of the
+        // formatted source (transform path), both of which break the
+        // documented "ttsc format only formats" guarantee. The
+        // short-circuit fires before either branch so format mode is a
+        // single concern regardless of how many compilers the project
+        // configures. Callers that want a recheck or a transform pass
+        // after format should run `ttsc check` / `ttsc build` as a
+        // separate invocation.
+        return checked;
+      }
       if (compilers.length !== 0) {
         assertSharedHostCompatibility(compilers, "emit");
         return appendBuildOutput(
@@ -143,6 +158,21 @@ export function runBuild(
     return result;
   }
 
+  if (options.format === true) {
+    // Format mode is write-only by contract — see the matching
+    // short-circuit in the with-native-plugins branch above. When no
+    // native plugin is loaded there is nothing for `ttsc format` to
+    // rewrite, so emit an empty success result rather than falling
+    // through to a tsgo pass that would surface unrelated type errors
+    // as if they were format failures.
+    return {
+      diagnostics: [],
+      status: 0,
+      stdout: "",
+      stderr: "",
+    };
+  }
+
   if (options.emit !== false && options.skipDiagnosticsCheck !== true) {
     const checked = runTsgo(execution, ["--noEmit"], options);
     if (checked.status !== 0) {
@@ -298,7 +328,7 @@ function createNativeCheckArgs(
   options: TtscBuildOptions,
 ): string[] {
   const args = [
-    "check",
+    nativeCheckSubcommand(options),
     "--tsconfig=" + execution.tsconfig,
     "--plugins-json=" + serializeNativePlugins(execution.nativePlugins),
     "--cwd=" + execution.projectRoot,
@@ -314,6 +344,18 @@ function createNativeCheckArgs(
   return args;
 }
 
+/**
+ * Decide which native plugin subcommand the lint sidecar should run for the
+ * current `runBuild` invocation. The launcher selects exactly one of `fix` /
+ * `format` / `check` via subcommand dispatch, so at most one of the
+ * `options.fix` / `options.format` booleans is true.
+ */
+function nativeCheckSubcommand(options: TtscBuildOptions): string {
+  if (options.format === true) return "format";
+  if (options.fix === true) return "fix";
+  return "check";
+}
+
 function serializeNativePlugins(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): string {

package/src/compiler/internal/sharedHostHelpers.ts

@@ -10,12 +10,12 @@ import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoa
  * plugin must declare itself with one of these names AND its source path must
  * resolve to a `package.json` whose `name` field matches.
  *
- * This whitelist exists because `@ttsc/banner`, `@ttsc/paths`, and `@ttsc/strip`
- * are AST-only mutators that operate on the same `*shimast.SourceFile` graph
- * and do not own emit. They are composed through `packages/ttsc/utility/host.go`,
- * so any one of their binaries can host the shared run. Third-party plugins
- * cannot participate in this fast path; they must opt into composition through
- * the explicit `ITtscPlugin.composes` field.
+ * This whitelist exists because `@ttsc/banner`, `@ttsc/paths`, and
+ * `@ttsc/strip` are AST-only mutators that operate on the same
+ * `*shimast.SourceFile` graph and do not own emit. They are composed through
+ * `packages/ttsc/utility/host.go`, so any one of their binaries can host the
+ * shared run. Third-party plugins cannot participate in this fast path; they
+ * must opt into composition through the explicit `ITtscPlugin.composes` field.
  */
 export const FIRST_PARTY_UTILITY_PLUGIN_NAMES: ReadonlySet<string> = new Set([
   "@ttsc/banner",
@@ -42,8 +42,8 @@ export function isFirstPartyUtilityTransformPlugin(
 /**
  * Walks upward from `source` (a directory or file path) up to four parent
  * levels searching for the nearest `package.json`. Returns the parsed manifest
- * object on success, or `undefined` when no manifest is found or parsing
- * fails. The depth bound mirrors the pre-existing inline implementations in
+ * object on success, or `undefined` when no manifest is found or parsing fails.
+ * The depth bound mirrors the pre-existing inline implementations in
  * `runBuild.ts` and `transformProjectInMemory.ts`.
  */
 export function readNearestPackageManifest(
@@ -77,10 +77,10 @@ export function readNearestPackageManifest(
  *
  * Two callers exist with subtly different error wording: the build path
  * (`runBuild.ts`) reports "multiple compiler native backends cannot share one
- * emit pass" while the source-to-source path
- * (`transformProjectInMemory.ts`) reports "cannot share one source-to-source
- * pass". The `pass` argument selects the appropriate phrase so the error
- * message remains diagnostic-grade instead of generic.
+ * emit pass" while the source-to-source path (`transformProjectInMemory.ts`)
+ * reports "cannot share one source-to-source pass". The `pass` argument selects
+ * the appropriate phrase so the error message remains diagnostic-grade instead
+ * of generic.
  */
 export function assertSharedHostCompatibility(
   plugins: readonly ITtscLoadedNativePlugin[],

package/src/defineTtscPlugin.ts

@@ -0,0 +1,26 @@
+import type { ITtscPlugin } from "./structures/ITtscPlugin";
+
+/**
+ * Identity helper for authoring `ITtscPlugin` descriptors with full literal
+ * type preservation.
+ *
+ * Two call shapes:
+ *
+ * - Object form: returns the descriptor unchanged but pins its narrowed type so
+ *   editor tooling and `satisfies` clauses can see exact field values.
+ * - Factory form: wraps a `(context) => descriptor` factory so the returned
+ *   function carries the literal descriptor type through to consumers without
+ *   forcing a manual `as const`.
+ *
+ * Pure pass-through at runtime — the function exists to teach TypeScript the
+ * const-narrowing the user would otherwise have to spell out.
+ */
+export function defineTtscPlugin<const T extends ITtscPlugin>(plugin: T): T;
+export function defineTtscPlugin<TContext, const T extends ITtscPlugin>(
+  factory: (context: TContext) => T,
+): (context: TContext) => T;
+export function defineTtscPlugin(
+  value: ITtscPlugin | ((context: unknown) => ITtscPlugin),
+): ITtscPlugin | ((context: unknown) => ITtscPlugin) {
+  return value;
+}

package/src/index.ts

@@ -1,11 +1,12 @@
 /**
- * ttsc — public TypeScript entry.
+ * Ttsc — public TypeScript entry.
  *
  * The package root intentionally exposes only the programmatic compiler class
  * and the plugin-author contracts. CLI launcher functions, binary resolution,
- * project parsing helpers, and native build helpers stay internal so the
- * public package surface remains small and stable.
+ * project parsing helpers, and native build helpers stay internal so the public
+ * package surface remains small and stable.
  */
 
 export * from "./TtscCompiler";
+export * from "./defineTtscPlugin";
 export * from "./structures/index";

package/src/launcher/internal/prepareExecution.ts

@@ -2,9 +2,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
 import { resolveEmittedJavaScript } from "../../compiler/internal/resolveEmittedJavaScript";
 import { runBuild } from "../../compiler/internal/runBuild";
-import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
 
 const PROCESS_CACHE_KEY = String(process.pid);

package/src/launcher/internal/resolveTtscserverBinary.ts

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Resolve the platform-specific ttscserver binary path. Looks first at the
+ * TTSCSERVER_BINARY environment override (must be absolute), then at the
+ * shipped per-platform npm package (`@ttsc/<platform>-<arch>/bin/ttscserver`),
+ * then at the local-build fallback under `packages/native/`.
+ *
+ * Mirrors `resolveBinary` for the ttsc helper so editors that install ttsc via
+ * pnpm see the LSP host alongside the existing helper.
+ */
+export function resolveTtscserverBinary(
+  opts: { env?: NodeJS.ProcessEnv } = {},
+): string | null {
+  const env = opts.env ?? process.env;
+  if (env.TTSCSERVER_BINARY && path.isAbsolute(env.TTSCSERVER_BINARY)) {
+    return env.TTSCSERVER_BINARY;
+  }
+
+  try {
+    return require.resolve(
+      `@ttsc/${process.platform}-${process.arch}/bin/${
+        process.platform === "win32" ? "ttscserver.exe" : "ttscserver"
+      }`,
+    );
+  } catch {
+    /* fall through to local lookup */
+  }
+
+  const local = defaultLocalBinaryPath();
+  if (local) return local;
+
+  return null;
+}
+
+function defaultLocalBinaryPath(): string | null {
+  const root = packageRootDir();
+  const candidate = path.resolve(
+    root,
+    "..",
+    "native",
+    process.platform === "win32" ? "ttscserver.exe" : "ttscserver",
+  );
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+function packageRootDir(): string {
+  const moduleDir = path.resolve(__dirname, "..", "..");
+  return fs.realpathSync.native?.(moduleDir) ?? fs.realpathSync(moduleDir);
+}

package/src/launcher/internal/runTtsc.ts

@@ -3,10 +3,10 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { TtscCompiler } from "../../TtscCompiler";
+import { resolveProjectConfig } from "../../compiler/internal/project/resolveProjectConfig";
 import { resolveBinary } from "../../compiler/internal/resolveBinary";
 import { runBuild } from "../../compiler/internal/runBuild";
 import { runSingleFileEmit } from "../../compiler/internal/runSingleFileEmit";
-import { resolveProjectConfig } from "../../compiler/internal/project/resolveProjectConfig";
 import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
 import { getCompilerVersionText } from "./getCompilerVersionText";
 
@@ -15,7 +15,7 @@ export function runTtsc(
 ): number {
   try {
     if (argv.length === 0) {
-      return runCompatibleBuild([], false);
+      return runCompatibleBuild([], "build");
     }
 
     const [command, ...rest] = argv as [string, ...string[]];
@@ -31,9 +31,13 @@ export function runTtsc(
         process.stdout.write(`${getCompilerVersionText()}\n`);
         return 0;
       case "build":
-        return runCompatibleBuild(rest, false);
+        return runCompatibleBuild(rest, "build");
       case "check":
-        return runCompatibleBuild(rest, true);
+        return runCompatibleBuild(rest, "check");
+      case "fix":
+        return runCompatibleBuild(rest, "fix");
+      case "format":
+        return runCompatibleBuild(rest, "format");
       case "clean":
         return runClean(rest);
       case "prepare":
@@ -42,10 +46,10 @@ export function runTtsc(
         return delegateToNative(argv);
       case "-p":
       case "--project":
-        return runCompatibleBuild(argv, false);
+        return runCompatibleBuild(argv, "build");
       default:
         if (isBuildAlias(command)) {
-          return runCompatibleBuild(argv, false);
+          return runCompatibleBuild(argv, "build");
         }
         process.stderr.write(
           `ttsc: unknown command ${JSON.stringify(command)}\n`,
@@ -68,15 +72,45 @@ function isBuildAlias(command: string): boolean {
   );
 }
 
-function runCompatibleBuild(
-  argv: readonly string[],
-  checkOnly: boolean,
-): number {
+type TtscMode = "build" | "check" | "fix" | "format";
+
+function runCompatibleBuild(argv: readonly string[], mode: TtscMode): number {
+  const checkOnly = mode !== "build";
   const options = normalizeBuildOptions(parseBuildArgs(argv, checkOnly));
+  if (mode === "fix") {
+    if (options.emit === true) {
+      throw new Error("ttsc: fix and --emit are mutually exclusive");
+    }
+    options.fix = true;
+    options.emit = false;
+  }
+  if (mode === "format") {
+    if (options.emit === true) {
+      throw new Error("ttsc: format and --emit are mutually exclusive");
+    }
+    options.format = true;
+    options.emit = false;
+  }
   if (options.watch) {
+    if (mode === "fix") {
+      throw new Error(
+        "ttsc: fix does not support watch mode; use ttsc --noEmit --watch for incremental checks",
+      );
+    }
+    if (mode === "format") {
+      throw new Error(
+        "ttsc: format does not support watch mode; use ttsc --noEmit --watch for incremental checks",
+      );
+    }
     return runWatch(options, checkOnly);
   }
   if (options.files.length !== 0) {
+    if (mode === "fix") {
+      throw new Error("ttsc: fix requires a project, not single-file mode");
+    }
+    if (mode === "format") {
+      throw new Error("ttsc: format requires a project, not single-file mode");
+    }
     return runSingleFile(options);
   }
   const result = runBuild(checkOnly ? { ...options, emit: false } : options);
@@ -268,6 +302,8 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
   let cwd: string | undefined;
   let emit: boolean | undefined = checkOnly ? false : undefined;
   const files: string[] = [];
+  let fix = false;
+  let format = false;
   let outDir: string | undefined;
   let preserveWatchOutput = false;
   let quiet = true;
@@ -348,6 +384,8 @@ function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
     cwd,
     emit,
     files,
+    fix,
+    format,
     outDir,
     preserveWatchOutput,
     quiet,
@@ -366,6 +404,8 @@ function printHelp(): void {
       "  ttsc -p tsconfig.json",
       "  ttsc --watch",
       "  ttsc --noEmit",
+      "  ttsc fix",
+      "  ttsc format",
       "  ttsc prepare [options]",
       "  ttsc clean [options]",
       "  ttsc version",
@@ -390,9 +430,11 @@ function printHelp(): void {
       "  Plugin modules are descriptors for ordered native transformer backends.",
       "  JS transformOutput/transformSource functions are not part of the public contract.",
       "",
-      "Compatibility aliases:",
+      "Subcommands:",
       "  ttsc build [options]       Same project build lane as `ttsc [options]`.",
       "  ttsc check [options]       Same as `ttsc --noEmit [options]`.",
+      "  ttsc fix [options]         Apply check-plugin lint + format edits, then run `ttsc check`.",
+      "  ttsc format [options]      Apply check-plugin format-class edits only (write-only, no type check).",
       "  ttsc prepare [options]     Build configured source-plugin binaries into cache.",
       "  ttsc clean [options]       Delete local source-plugin cache directories.",
     ].join("\n"),

package/src/launcher/internal/runTtscserver.ts

@@ -0,0 +1,92 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import * as os from "node:os";
+
+import { resolveTtscserverBinary } from "./resolveTtscserverBinary";
+
+/**
+ * Drive the ttscserver native binary from a node launcher. The launcher is
+ * deliberately thin: argument parsing, version banners, and help text are owned
+ * by the Go binary so future flags only need to change one layer. The JS side
+ * performs only:
+ *
+ * - Resolve the platform binary,
+ * - Inject `--stdio` when the first arg is not a meta-command,
+ * - Delegate to the binary with inherited stdio so OS-level signals reach the
+ *   child via the parent's process group.
+ */
+export function runTtscserver(
+  argv: readonly string[] = process.argv.slice(2),
+): number {
+  const binary = resolveTtscserverBinary();
+  if (!binary) {
+    process.stderr.write(
+      [
+        `ttscserver: platform-specific binary not found (@ttsc/${process.platform}-${process.arch}).`,
+        `Set TTSCSERVER_BINARY to an absolute path or reinstall ttsc with optional dependencies enabled.`,
+      ].join("\n") + "\n",
+    );
+    return 1;
+  }
+  ensureExecutable(binary);
+
+  const args = needsStdio(argv) ? ["--stdio", ...argv] : [...argv];
+  const result = spawnSync(binary, args, {
+    stdio: "inherit",
+    env: process.env,
+    windowsHide: true,
+  });
+  if (result.error) {
+    process.stderr.write(`ttscserver: ${result.error.message}\n`);
+    return 1;
+  }
+  if (result.signal) {
+    // POSIX convention: 128 + signum so wrappers (bash, npm-script, CI)
+    // can decode the signal that killed the child (130 = SIGINT, 143 =
+    // SIGTERM, etc.). On Windows, `spawnSync` does not surface a signal
+    // (TerminateProcess carries no signum) so this branch is POSIX-only
+    // by design; Windows-killed children take the `result.status ?? 1`
+    // path below.
+    const signum = (os.constants.signals as Record<string, number | undefined>)[
+      result.signal
+    ];
+    return typeof signum === "number" ? 128 + signum : 1;
+  }
+  return result.status ?? 1;
+}
+
+/**
+ * `--stdio` is the only transport the native host accepts today. The launcher
+ * injects it only when the first argv token looks like a forwarded option;
+ * meta-commands (`-v`, `--help`, `version`, etc.) pass through untouched so the
+ * Go binary owns the canonical banner. This mirrors
+ * `cmd/ttscserver/main.go::run`, which dispatches on `args[0]` only.
+ */
+export function needsStdio(argv: readonly string[]): boolean {
+  if (argv.length === 0) return false;
+  if (argv.includes("--stdio")) return false;
+  const head = argv[0];
+  if (
+    head === "-v" ||
+    head === "--version" ||
+    head === "version" ||
+    head === "-h" ||
+    head === "--help" ||
+    head === "help"
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/** Mirror the ttsc helper-binary chmod hint so first-run from npm works. */
+function ensureExecutable(binary: string): void {
+  if (process.platform === "win32") return;
+  try {
+    const mode = fs.statSync(binary).mode & 0o777;
+    if ((mode & 0o111) !== 0) return;
+    fs.chmodSync(binary, mode | 0o755);
+  } catch {
+    /* spawn will surface the underlying error */
+  }
+}

package/src/launcher/internal/runTtsx.ts

@@ -1,5 +1,5 @@
-import fs from "node:fs";
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 
 import { getCompilerVersionText } from "./getCompilerVersionText";

package/src/launcher/ttscserver.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runTtscserver } from "./internal/runTtscserver";
+
+const code = runTtscserver(process.argv.slice(2));
+if (typeof code === "number") {
+  process.exitCode = code;
+}