ttsc 0.30.4 → 0.31.0

package/src/compiler/internal/build/parseProjectInputSnapshot.ts

@@ -0,0 +1,91 @@
+import type { ITtscLoadedNativePlugin } from "../../../structures/internal/ITtscLoadedNativePlugin";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import { isAbsoluteLocalProjectInputPath } from "./isAbsoluteLocalProjectInputPath";
+
+/**
+ * Parse and validate the JSON a native host printed for `project-inputs`.
+ *
+ * Every path in the snapshot (root, files, globs, reload files and directories)
+ * must satisfy host-native absolute namespace admission; relative/empty paths
+ * and Windows device namespaces are rejected with the plugin's name. This is
+ * native namespace admission, not an existence, access or watcher-capability
+ * check; silently dropping rejected declarations would hide an unsupported
+ * dependency. Optional reload lists default to empty.
+ *
+ * These checks cover host-published input lists; the later merge reconstructs
+ * declared alias lists from these spellings rather than trusting extra JSON.
+ *
+ * @evidence contracts/common.md#principled-implementation Unknown JSON is narrowed by required object and string-array checks, then native path admission; missing reload arrays receive the protocol's empty meaning.
+ * @evidence contracts/common.md#clear-and-simple-design JSON syntax, snapshot shape and path admission are separate checks, yielding plugin-attributed errors before normalized arrays are returned.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid published inputs throw instead of being silently dropped or replaced by guessed project paths.
+ * @evidence contracts/common.md#meaningful-documentation Native prose describes invalid input effects, optional reload defaults and the later reconstruction of alias metadata.
+ * @evidence contracts/portability.md#os-neutral-implementation The host-platform path classifier admits native drive/UNC or POSIX absolute input syntax and rejects device namespaces without case folding or shell interpretation.
+ * @evidence contracts/performance.md#efficient-algorithms JSON parsing/property copying follows payload/field bytes; field-array checks and pair construction visit all declared paths before the first-invalid search. Native path classification adds each path's scan/normalization costs and temporary text; pair storage grows with path count, and this parser supplies no payload-byte ceiling.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Host output must be validated on this invocation; this parser does not coordinate repeated host production or retain an earlier snapshot.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Parsed values and validation arrays are local or returned, without persistent retention or acquired resources.
+ */
+export function parseProjectInputSnapshot(
+  text: string,
+  plugin: ITtscLoadedNativePlugin,
+): ITtscProjectInputSnapshot {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `ttsc.project-inputs: ${plugin.name ?? plugin.binary} returned invalid JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    typeof (value as { root?: unknown }).root !== "string" ||
+    !isStringArray((value as { files?: unknown }).files) ||
+    !isStringArray((value as { globs?: unknown }).globs) ||
+    ((value as { reloadDirectories?: unknown }).reloadDirectories !==
+      undefined &&
+      !isStringArray(
+        (value as { reloadDirectories?: unknown }).reloadDirectories,
+      )) ||
+    ((value as { reloadFiles?: unknown }).reloadFiles !== undefined &&
+      !isStringArray((value as { reloadFiles?: unknown }).reloadFiles))
+  ) {
+    throw new Error(
+      `ttsc.project-inputs: ${plugin.name ?? plugin.binary} returned an invalid snapshot`,
+    );
+  }
+  const snapshot = value as unknown as ITtscProjectInputSnapshot;
+  const invalid = [
+    ["root", snapshot.root],
+    ...snapshot.files.map((file) => ["file", file] as const),
+    ...snapshot.globs.map((glob) => ["glob", glob] as const),
+    ...(snapshot.reloadDirectories ?? []).map(
+      (directory) => ["reload directory", directory] as const,
+    ),
+    ...(snapshot.reloadFiles ?? []).map(
+      (file) => ["reload file", file] as const,
+    ),
+  ].find(
+    ([, location]) =>
+      location.length === 0 || !isAbsoluteLocalProjectInputPath(location),
+  );
+  if (invalid !== undefined) {
+    throw new Error(
+      `ttsc.project-inputs: ${plugin.name ?? plugin.binary} returned an invalid snapshot: ${invalid[0]} ${JSON.stringify(invalid[1])} is not an absolute local path`,
+    );
+  }
+  return {
+    ...snapshot,
+    reloadDirectories: snapshot.reloadDirectories ?? [],
+    reloadFiles: snapshot.reloadFiles ?? [],
+  };
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === "string")
+  );
+}

package/src/compiler/internal/build/planResidentCheckEntries.ts

@@ -0,0 +1,55 @@
+import type { ITtscLoadedNativePlugin } from "../../../structures/internal/ITtscLoadedNativePlugin";
+import type { ResidentCheckEntryPlan } from "./ResidentCheckEntryPlan";
+
+/**
+ * Plan every configured check entry while sharing resident processes only by
+ * binary/name/argument identity.
+ *
+ * Forwarded compiler flags are part of that identity even though they travel
+ * through the environment. Configuration positions remain distinct so shared
+ * processes do not collapse check executions or change delivery order.
+ *
+ * @evidence contracts/common.md#principled-implementation Capability-gated resident keys include binary, plugin name, argv and forwarded compiler payload, while each check retains its own configuration index.
+ * @evidence contracts/common.md#clear-and-simple-design Filtering selects check-stage entries and mapping records their execution plan; process-key construction is isolated from per-entry scheduling.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Resident support comes from declared capabilities rather than binary-name guesses; duplicate entries are not silently skipped.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes process sharing, environment-carried compiler arguments and separate configured executions.
+ * @evidence contracts/portability.md#os-neutral-implementation Binary and argv remain separate native process inputs; JSON encodes argument boundaries without shell quoting or path case assumptions.
+ * @evidence contracts/performance.md#efficient-algorithms Filtering scans all plugins, then mapping visits selected checks and calls the argument composer once per entry. Cost includes those composer calls and resident-key string/JSON bytes; the current composer serializes the full plugin manifest separately for every configured check. Returned storage scales with selected entries and their argument/key bytes.
+ * @evidence contracts/performance.md#reuse-equivalent-work Equivalent resident startup selections receive the same key; the session additionally requires stable execution context and resets topology before reuse.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Plans describe process selection but acquire no sidecars or retained requests themselves.
+ */
+export function planResidentCheckEntries(
+  plugins: readonly ITtscLoadedNativePlugin[],
+  createArgs: (plugin: ITtscLoadedNativePlugin) => string[],
+  // Part of the process identity even though it never appears in argv: the
+  // forwarded tsgo payload rides the environment, and a resident process holds
+  // the compiler options it was started with. Two cycles that forward different
+  // flags must not share one warm Program.
+  tsgoArgs?: string,
+  compilerArgsCwd?: string,
+): ResidentCheckEntryPlan[] {
+  return plugins
+    .filter((candidate) => candidate.stage === "check")
+    .map((plugin, entryIndex) => {
+      const args = createArgs(plugin);
+      return {
+        args,
+        entryIndex,
+        key:
+          plugin.capabilities?.residentCheck === true
+            ? residentCheckProcessKey(plugin, args, tsgoArgs, compilerArgsCwd)
+            : undefined,
+        plugin,
+      };
+    });
+}
+
+function residentCheckProcessKey(
+  plugin: ITtscLoadedNativePlugin,
+  args: readonly string[],
+  tsgoArgs?: string,
+  compilerArgsCwd?: string,
+): string {
+  return `${plugin.binary}\0${plugin.name}\0${JSON.stringify(args)}\0${tsgoArgs ?? ""}\0${compilerArgsCwd ?? ""}`;
+}

package/src/compiler/internal/build/privateRuntimeRootDir.ts

@@ -0,0 +1,33 @@
+import path from "node:path";
+
+/**
+ * Select the layout root for JavaScript written only to a runtime-owned emit
+ * directory. Explicit roots and composite-project containment remain compiler
+ * policy. An ordinary project without a root uses its native volume root so
+ * adding private output does not reject same-volume imports outside the config
+ * directory. A different Windows volume still cannot fit this one output root
+ * and remains subject to the compiler's cross-volume layout diagnostics. This
+ * changes only private output coordinates, not the program's input set. Actual
+ * emitted-source provenance remains required before serving any file.
+ *
+ * @evidence contracts/common.md#principled-implementation Runtime-injected output has a separate layout root without widening an explicit or composite root or changing source membership and type options.
+ * @evidence contracts/common.md#clear-and-simple-design One path policy is shared by compiler arguments and runtime ownership metadata.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No extra compiler pass, filename-derived emit authority or unchecked execution substitutes for the selected project and its actual output provenance.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes private output coordinates, explicit containment and actual source membership.
+ * @evidence contracts/portability.md#os-neutral-implementation Node's native path parser preserves drive and UNC volume roots; explicit relative roots resolve against their declaring project. This selects lexical layout and makes no filesystem identity or case-policy observation.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed branch sequence delegates path parsing or resolution whose work and temporary strings scale with the supplied path text; no filesystem enumeration or compiler execution occurs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This path policy caches no completed or in-flight producer; callers own runtime generation reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only a returned path string transfers to the caller; no handle, generation or history is retained.
+ */
+export function privateRuntimeRootDir(
+  projectRoot: string,
+  rootDir: unknown,
+  composite: unknown,
+): string {
+  if (typeof rootDir === "string") {
+    return path.isAbsolute(rootDir)
+      ? rootDir
+      : path.resolve(projectRoot, rootDir);
+  }
+  return composite === true ? projectRoot : path.parse(projectRoot).root;
+}

package/src/compiler/internal/build/residentCheckRequest.ts

@@ -0,0 +1,41 @@
+import path from "node:path";
+
+import { type ResidentCheckRequest } from "../ResidentCheckRequest";
+import type { ResidentCheckWatchChange } from "./ResidentCheckWatchChange";
+
+/**
+ * Translate one watch change into a resident check request payload. The process
+ * owner serializes this record into the sidecar's line protocol.
+ *
+ * Paths are resolved against `cwd`, deduplicated, and sorted, so two cycles
+ * that observed the same edits in a different order send identical requests.
+ * `reload` is not part of the wire protocol: the session handles it by
+ * discarding its processes before any request is sent.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolving and sorting sets gives order-independent wire paths; invalidation remains explicit and coordinator-only reload is omitted from the sidecar payload.
+ * @evidence contracts/common.md#clear-and-simple-design One local normalizer serves changed and external lists, while the result literal exposes which nonempty wire fields are present.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only protocol-defined fields are emitted; reload is handled by the session rather than faked as a special changed filename.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish canonical path order from reload's separate session effect.
+ * @evidence contracts/portability.md#os-neutral-implementation node:path resolves native spellings against the supplied cwd and collapses dot segments; it preserves case and does not resolve symlink targets or certify physical filesystem identity.
+ * @evidence contracts/performance.md#efficient-algorithms Each supplied path is resolved directly into a set without an intermediate mapped array. Resolution and set membership include path-string work; sorting U distinct paths uses O(U log U) string comparisons, and temporary storage holds distinct path bytes plus returned references.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This converts one change event without coordinating a persistent producer; process reuse belongs to the session.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local sets become returned arrays and this converter owns no retained watch buffer or sidecar.
+ */
+export function residentCheckRequest(
+  change: ResidentCheckWatchChange,
+  cwd: string,
+): ResidentCheckRequest {
+  const normalize = (values: readonly string[] | undefined): string[] => {
+    const paths = new Set<string>();
+    for (const value of values ?? []) paths.add(path.resolve(cwd, value));
+    return [...paths].sort();
+  };
+  const changed = normalize(change.changed);
+  const external = normalize(change.external);
+  return {
+    ...(change.invalidate === true ? { invalidate: true } : {}),
+    ...(changed.length === 0 ? {} : { changed }),
+    ...(external.length === 0 ? {} : { external }),
+  };
+}

package/src/compiler/internal/build/runBuild.ts

@@ -0,0 +1,61 @@
+import type { TtscBuildResult } from "../../../structures/internal/TtscBuildResult";
+import { BuildExecution } from "./BuildExecution";
+import { BuildTiming } from "./BuildTiming";
+import type { RunBuildOptions } from "./RunBuildOptions";
+
+/**
+ * Run `ttsc` against a tsconfig. Returns once the binary exits so the CLI can
+ * decide how to surface diagnostics. Non-zero process exit is returned as a
+ * result; configuration resolution and process-launch failures may throw.
+ *
+ * Project-free terminal flags bypass project/plugin setup when applicable.
+ * Required emit provenance preserves compiler selection and exposes unknown
+ * ownership when the selected producer cannot establish the requested
+ * relation.
+ *
+ * @evidence contracts/common.md#principled-implementation Shared preparation selects project and plugins before execution, while project-free terminal requests take their supported direct compiler path; timing is appended after the resulting build phase.
+ * @evidence contracts/common.md#clear-and-simple-design The public synchronous entry owns timing and delegates setup/execution to BuildExecution, keeping the same build policy available to watch sessions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Terminal bypass follows compiler flag semantics and plugin failures remain visible; no retry hides configuration or spawn errors.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes returned exit failures from thrown setup/launch errors and explains the project-free branch.
+ * @evidence contracts/portability.md#os-neutral-implementation Execution selection and spawning use the shared native path/process boundaries with cwd and separate argv, rather than constructing a shell command here.
+ * @evidence contracts/performance.md#efficient-algorithms Timing creation and terminal selection make their own flag projections before the selected preparation/execution path. Delegated configuration, plugin, native/provenance and diagnostic work follows its actual input/report sizes; timing formatting scans ledger labels and output. No measured dominance or duration/output ceiling is established by this wrapper.
+ * @evidence contracts/performance.md#reuse-equivalent-work A resolved execution context is carried through preparation and execution, so this build does not reload its plugin selection between phases.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The ledger and execution state are build-owned, while returned output/proof/diagnostic records transfer to the caller; no resident handle or historical build is stored here. Delegated native/probe/artifact acquisition and cleanup may be best effort, and thrown setup can precede some cleanup boundaries. This wrapper supplies no duration/output bound or descendant-release certification.
+ */
+export function runBuild(options: RunBuildOptions = {}): TtscBuildResult {
+  const timing = BuildTiming.createBuildTiming(options);
+  const result = runBuildTimed(options, timing);
+  return BuildTiming.appendTimingOutput(result, timing);
+}
+
+function runBuildTimed(
+  options: RunBuildOptions,
+  timing: BuildTiming.BuildTiming,
+): TtscBuildResult {
+  const projectFree = BuildExecution.runProjectFreeTerminalFlag(options);
+  if (projectFree !== null) return projectFree;
+  const setupStartedAt = process.hrtime.bigint();
+  const execution = BuildExecution.resolveExecutionContext(options);
+  return runBuildWithExecution(options, timing, execution, setupStartedAt);
+}
+
+function runBuildWithExecution(
+  options: RunBuildOptions,
+  timing: BuildTiming.BuildTiming,
+  execution: ReturnType<typeof BuildExecution.resolveExecutionContext>,
+  setupStartedAt: bigint,
+): TtscBuildResult {
+  const prepared = BuildExecution.prepareBuildExecution(
+    options,
+    timing,
+    execution,
+    setupStartedAt,
+  );
+  if (prepared.result !== undefined) return prepared.result;
+  return BuildExecution.runPreparedBuild(
+    options,
+    timing,
+    execution,
+    prepared.buildOptions,
+  );
+}