ttsc 0.19.2 → 0.20.0

package/src/compiler/internal/startResidentTransform.ts

@@ -4,7 +4,10 @@ import { loadProjectPlugins } from "../../plugin/internal/loadProjectPlugins";
 import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
 import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
 import { readProjectConfig } from "./project/readProjectConfig";
-import { ResidentTransformProcess } from "./residentTransformProcess";
+import {
+  ResidentTransformProcess,
+  normalizeRequestTimeoutMs,
+} from "./residentTransformProcess";
 import { resolveBinary } from "./resolveBinary";
 import { resolveTsgo } from "./resolveTsgo";
 import {
@@ -23,6 +26,11 @@ export interface StartedResidentTransform {
   projectRoot: string;
 }
 
+/** Construction controls owned by the resident request client. */
+export interface StartResidentTransformOptions {
+  requestTimeoutMs?: number;
+}
+
 /**
  * Start a resident `serve` host for the configured project.
  *
@@ -40,7 +48,9 @@ export interface StartedResidentTransform {
  */
 export function startResidentTransform(
   context: ITtscCompilerContext,
+  options: StartResidentTransformOptions = {},
 ): StartedResidentTransform {
+  const requestTimeoutMs = normalizeRequestTimeoutMs(options.requestTimeoutMs);
   const cwd = path.resolve(context.cwd ?? process.cwd());
   const project = readProjectConfig({
     cwd,
@@ -80,6 +90,7 @@ export function startResidentTransform(
     binary: host.binary,
     cwd: project.root,
     env: residentEnv(context, tsgoBinary, loaded.nativePlugins),
+    requestTimeoutMs,
   });
   return { process: resident, projectRoot: project.root };
 }

package/src/compiler/internal/transformProjectInMemory.ts

@@ -488,6 +488,12 @@ function parseDependencyLists(
  * `dependencies`: non-object sections are dropped, edge entries that are not
  * string arrays are dropped, and non-string list members are filtered. A
  * section carrying nothing usable collapses to `undefined`.
+ *
+ * `candidates` is the one optional member, so an empty one is left off the
+ * result instead of being materialized as `{}`. The host omits the key when it
+ * has no superseding candidate to report, and a consumer that narrows on the
+ * declared optional type must see the same shape whether it reads the decoded
+ * envelope or the wire.
  */
 function parseReferenceGraph(
   value: unknown,
@@ -496,21 +502,26 @@ function parseReferenceGraph(
     return undefined;
   }
   const section = value as {
+    candidates?: unknown;
     configs?: unknown;
     edges?: unknown;
     globals?: unknown;
   };
+  const candidates = parseDependencyLists(section.candidates) ?? {};
   const edges = parseDependencyLists(section.edges) ?? {};
   const globals = parseFileList(section.globals) ?? [];
   const configs = parseFileList(section.configs) ?? [];
   if (
+    Object.keys(candidates).length === 0 &&
     Object.keys(edges).length === 0 &&
     globals.length === 0 &&
     configs.length === 0
   ) {
     return undefined;
   }
-  return { configs, edges, globals };
+  return Object.keys(candidates).length === 0
+    ? { configs, edges, globals }
+    : { candidates, configs, edges, globals };
 }
 
 /**

package/src/flags/parser.ts

@@ -11,7 +11,11 @@
 // The schema is the spec; behaviour at every layer boundary is determined by
 // the FlagSpec attributes, not by ad-hoc `if (arg === "--foo")` branches.
 import type { AnySubcommand, FlagSpec, ValueValidator } from "./schema";
-import { FLAG_BY_NAME, flagsForSubcommand } from "./schema";
+import {
+  flagsForSubcommand,
+  normalizeFlagToken,
+  resolveFlagSpec,
+} from "./schema";
 
 /**
  * Per-subcommand parse result. `values` is keyed by the canonical flag name
@@ -22,6 +26,16 @@ import { FLAG_BY_NAME, flagsForSubcommand } from "./schema";
 export interface ParseResult {
   /** Canonical flag name → resolved value. */
   readonly values: ReadonlyMap<string, string | boolean | number>;
+  /**
+   * Canonical flag name → every accepted value, in argv order. Populated only
+   * for flags declared `repeatable` in `FLAG_SCHEMA` (`ttsx -r a -r b`), where
+   * the last-value-wins `values` entry is not the whole answer. Read it through
+   * `getStringList`.
+   */
+  readonly repeated: ReadonlyMap<
+    string,
+    readonly (string | boolean | number)[]
+  >;
   /** Flags the engine did not consume — forwarded to tsgo. */
   readonly passthrough: readonly string[];
   /** Bare non-flag positional arguments, in original order. */
@@ -73,6 +87,10 @@ export interface ParseOptions {
    * arity from the flag itself (it has no schema for a truly unknown flag); the
    * predicate is the only signal that separates a forwarded value from a real
    * input file, and both callers key it on the TypeScript source extension.
+   *
+   * Every path that can move a bare token out of `positional` consults it: the
+   * main loop below and `forwardKnownButUnaccepted`, which answers the same
+   * question for a schema-known flag this subcommand does not accept.
    */
   readonly isPositional?: (token: string) => boolean;
 }
@@ -96,11 +114,14 @@ export function parseFlags(opts: ParseOptions): ParseResult {
     // flag at the launcher boundary (the RC-1 / RC-2 class the schema
     // is meant to make impossible).
     if (!flag.consumedBy.includes("launcher")) continue;
-    accepted.set(flag.name, flag);
-    for (const alias of flag.aliases ?? []) accepted.set(alias, flag);
+    accepted.set(normalizeFlagToken(flag.name), flag);
+    for (const alias of flag.aliases ?? []) {
+      accepted.set(normalizeFlagToken(alias), flag);
+    }
   }
 
   const values = new Map<string, string | boolean | number>();
+  const repeated = new Map<string, (string | boolean | number)[]>();
   const passthrough: string[] = [];
   const positional: string[] = [];
   const tail: string[] = [];
@@ -130,42 +151,61 @@ export function parseFlags(opts: ParseOptions): ParseResult {
       continue;
     }
 
-    // `--foo=value` / `-p=value` form: split before resolving against the
-    // schema. Both long (`--foo`) and short (`-p`) aliases support the
-    // inline-value shape — without splitting the short form, `-p=value`
-    // would fall through as an unknown token and be forwarded to tsgo,
-    // bypassing the launcher's own consumer (e.g. plugin discovery against
-    // the wrong project root).
-    const equalsIndex = current.startsWith("-") ? current.indexOf("=") : -1;
-    const token = equalsIndex === -1 ? current : current.slice(0, equalsIndex);
-    const inlineValue =
-      equalsIndex === -1 ? undefined : current.slice(equalsIndex + 1);
+    // Only a `-`-prefixed token can name a flag. Bare tokens are input files
+    // and flag values; resolving one against the schema would let the `all` of
+    // `--target all` masquerade as `--all` now that the lookup is dash- and
+    // case-insensitive.
+    if (current.startsWith("-")) {
+      // `--foo=value` / `-p=value` form: split before resolving against the
+      // schema. Both long (`--foo`) and short (`-p`) aliases support the
+      // inline-value shape — without splitting the short form, `-p=value`
+      // would fall through as an unknown token and be forwarded to tsgo,
+      // bypassing the launcher's own consumer (e.g. plugin discovery against
+      // the wrong project root).
+      const equalsIndex = current.indexOf("=");
+      const token =
+        equalsIndex === -1 ? current : current.slice(0, equalsIndex);
+      const inlineValue =
+        equalsIndex === -1 ? undefined : current.slice(equalsIndex + 1);
 
-    const flag = accepted.get(token);
-    if (flag !== undefined) {
-      consumeFlag(values, flag, token, inlineValue, head, opts.errorPrefix);
-      continue;
-    }
+      // Resolution is by flag identity, not by exact spelling: `--NOEMIT` and
+      // `-noEmit` are the same option to the compiler ttsc forwards to, so they
+      // must be the same option here. Otherwise a case variant of a ttsc-owned
+      // flag falls through to the escape hatch below and tsgo honours it while
+      // every ttsc-side consumer stays silent.
+      const flag = accepted.get(normalizeFlagToken(token));
+      if (flag !== undefined) {
+        consumeFlag(
+          values,
+          repeated,
+          flag,
+          token,
+          inlineValue,
+          head,
+          opts.errorPrefix,
+        );
+        continue;
+      }
 
-    // Token IS a known flag but is not accepted by THIS subcommand. The
-    // engine forwards it to tsgo just like an unknown flag — the same
-    // policy the bare-lane parser applied (RC-1 prevention).
-    const globalFlag = FLAG_BY_NAME.get(token);
-    if (globalFlag !== undefined) {
-      forwardKnownButUnaccepted(
-        passthrough,
-        globalFlag,
-        current,
-        inlineValue,
-        head,
-      );
-      continue;
-    }
+      // Token IS a known flag but is not accepted by THIS subcommand. The
+      // engine forwards it to tsgo just like an unknown flag — the same
+      // policy the bare-lane parser applied (RC-1 prevention).
+      const globalFlag = resolveFlagSpec(token);
+      if (globalFlag !== undefined) {
+        forwardKnownButUnaccepted(
+          passthrough,
+          globalFlag,
+          current,
+          inlineValue,
+          head,
+          opts.isPositional,
+        );
+        continue;
+      }
 
-    // Truly unknown `-`-prefixed token: forward to tsgo verbatim. This
-    // is what makes `ttsc --strict file.ts` work — ttsc does not need to
-    // re-implement every tsgo flag.
-    if (current.startsWith("-")) {
+      // Truly unknown `-`-prefixed token: forward to tsgo verbatim. This
+      // is what makes `ttsc --strict file.ts` work — ttsc does not need to
+      // re-implement every tsgo flag.
       passthrough.push(current);
       continue;
     }
@@ -194,7 +234,7 @@ export function parseFlags(opts: ParseOptions): ParseResult {
     for (const token of remainder) sink.push(token);
   }
 
-  return { values, passthrough, positional, tail };
+  return { values, repeated, passthrough, positional, tail };
 }
 
 /**
@@ -204,12 +244,20 @@ export function parseFlags(opts: ParseOptions): ParseResult {
  */
 function consumeFlag(
   values: Map<string, string | boolean | number>,
+  repeated: Map<string, (string | boolean | number)[]>,
   flag: FlagSpec,
   token: string,
   inlineValue: string | undefined,
   rest: string[],
   errorPrefix: string,
 ): void {
+  const record = (value: string | boolean | number): void => {
+    values.set(flag.name, value);
+    if (flag.repeatable !== true) return;
+    const list = repeated.get(flag.name);
+    if (list === undefined) repeated.set(flag.name, [value]);
+    else list.push(value);
+  };
   if (flag.kind === "boolean") {
     if (inlineValue !== undefined) {
       // `--flag=false` / `--flag=true` inline form. Anything other than
@@ -224,7 +272,7 @@ function consumeFlag(
           )}`,
         );
       }
-      values.set(flag.name, literal);
+      record(literal);
       return;
     }
     // Space form `--flag true` / `--flag false`: peek the next token and
@@ -236,11 +284,11 @@ function consumeFlag(
       const peek = parseBooleanLiteral(rest[0]!);
       if (peek !== undefined) {
         rest.shift();
-        values.set(flag.name, peek);
+        record(peek);
         return;
       }
     }
-    values.set(flag.name, true);
+    record(true);
     return;
   }
 
@@ -249,10 +297,10 @@ function consumeFlag(
       ? inlineValue
       : takeValueToken(token, rest, errorPrefix);
   if (flag.validator === "positiveInt") {
-    values.set(flag.name, validatePositiveInt(token, raw, errorPrefix));
+    record(validatePositiveInt(token, raw, errorPrefix));
     return;
   }
-  values.set(flag.name, raw);
+  record(raw);
 }
 
 /**
@@ -320,6 +368,14 @@ function validatePositiveInt(
  * accept. The launcher will hand it to tsgo (or to native sidecars via
  * `--tsgo-args`); without this branch the parser would lose the value token of
  * a `--flag value` pair.
+ *
+ * `isPositional` is the same predicate the main loop applies, and applying it
+ * here is what makes the file's own claim true — that the two value-resolution
+ * paths agree, and that the predicate is the only signal separating a forwarded
+ * value from a real input. Without it this branch took the next bare token on
+ * behalf of a flag that does not own it, so `ttsc --pretty a.ts` lost `a.ts`
+ * out of `positional` and silently switched from single-file mode to project
+ * mode (issue #663's failure shape, reached through the sibling branch).
  */
 function forwardKnownButUnaccepted(
   passthrough: string[],
@@ -327,6 +383,7 @@ function forwardKnownButUnaccepted(
   original: string,
   inlineValue: string | undefined,
   rest: string[],
+  isPositional: ((token: string) => boolean) | undefined,
 ): void {
   passthrough.push(original);
   // Boolean flags carry no value. `--foo=value` already encodes the value
@@ -337,6 +394,7 @@ function forwardKnownButUnaccepted(
   }
   if (rest.length === 0) return;
   if (rest[0]!.startsWith("-")) return;
+  if (isPositional !== undefined && isPositional(rest[0]!)) return;
   passthrough.push(rest.shift()!);
 }
 
@@ -374,6 +432,19 @@ export function getString(
   return undefined;
 }
 
+/**
+ * Return every string value accepted for a `repeatable` flag, in argv order.
+ *
+ * `values` keeps only the last occurrence, which is the wrong answer for a flag
+ * whose whole point is repetition (`ttsx -r a -r b` preloads both). Returns an
+ * empty array when the flag never appeared.
+ */
+export function getStringList(result: ParseResult, flag: string): string[] {
+  return (result.repeated.get(flag) ?? []).filter(
+    (value): value is string => typeof value === "string",
+  );
+}
+
 /** Return the numeric value of `flag` or `undefined` if not present. */
 export function getNumber(
   result: ParseResult,

package/src/flags/schema.ts

@@ -26,6 +26,7 @@
 export type TtscSubcommand =
   | "ttsc"
   | "build"
+  | "cache"
   | "check"
   | "fix"
   | "format"
@@ -130,6 +131,26 @@ export interface FlagSpec {
    */
   readonly terminal?: boolean;
 
+  /**
+   * `true` when a `terminal` flag's meaning does not presuppose a resolved
+   * project, so ttsc must answer it before project resolution runs (`--init`
+   * writes the starter tsconfig, `--all` and `-?` print tsgo's help). Without
+   * this split `ttsc --init` failed with "could not find tsconfig.json …" in
+   * the only directory where it is useful.
+   *
+   * `--showConfig` and `--listFilesOnly` are terminal but deliberately NOT
+   * project-free: both describe a project, so failing without one is correct.
+   */
+  readonly projectFree?: boolean;
+
+  /**
+   * `true` when every occurrence of a repeated `value` flag counts rather than
+   * the last one winning (`ttsx -r a -r b` preloads both). The engine keeps the
+   * last value in `ParseResult.values` for callers that want a single answer
+   * and records the complete ordered list in `ParseResult.repeated`.
+   */
+  readonly repeatable?: boolean;
+
   /**
    * `true` when ttsc may add this flag to tsgo internally and post-process the
    * output. If the user also forwards the same flag, ttsc keeps the
@@ -201,6 +222,7 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
       "ttsc",
       "ttsx",
       "build",
+      "cache",
       "check",
       "fix",
       "format",
@@ -217,6 +239,7 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
       "ttsc",
       "ttsx",
       "build",
+      "cache",
       "check",
       "fix",
       "format",
@@ -316,6 +339,7 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
       "ttsc",
       "ttsx",
       "build",
+      "cache",
       "check",
       "fix",
       "format",
@@ -325,6 +349,13 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
     consumedBy: ["launcher"],
     description: "Override the runner and source-plugin cache root.",
   },
+  {
+    name: "--json",
+    kind: "boolean",
+    subcommands: ["cache"],
+    consumedBy: ["launcher"],
+    description: "Print cache paths as JSON.",
+  },
 
   // -------------------------------------------------------------------------
   // Threading (tsgo-native; lint host opts in via capability).
@@ -354,9 +385,10 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
     name: "--require",
     aliases: ["-r"],
     kind: "value",
+    repeatable: true,
     subcommands: ["ttsx"],
     consumedBy: ["launcher"],
-    description: "Preload a module before the entrypoint (ttsx).",
+    description: "Preload a module before the entrypoint (ttsx; repeatable).",
   },
   {
     name: "--no-plugins",
@@ -382,8 +414,14 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
       "Print the list of emitted files (forwarded to tsgo; ttsc keeps the lines when forwarded).",
   },
   {
+    // tsgo declares `--pretty` as `type: boolean`, so it occupies one argv
+    // token and consumes a following one only when that token is the literal
+    // `true` or `false` — the shape the engine's boolean branch implements.
+    // Declaring it `value` made the forwarding path swallow whatever followed,
+    // so `ttsc --pretty a.ts` lost its input file and silently switched to
+    // project mode.
     name: "--pretty",
-    kind: "value",
+    kind: "boolean",
     subcommands: ["ttsc", "ttsx", "build", "check", "fix", "format"],
     consumedBy: ["tsgo"],
     forwardTo: "tsgo",
@@ -435,6 +473,7 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
     consumedBy: ["tsgo"],
     forwardTo: "tsgo",
     terminal: true,
+    projectFree: true,
     description: "Print the full tsgo CLI help and exit.",
   },
   {
@@ -444,8 +483,24 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
     consumedBy: ["tsgo"],
     forwardTo: "tsgo",
     terminal: true,
+    projectFree: true,
     description: "Write a starter tsconfig.json and exit (forwarded to tsgo).",
   },
+  {
+    // tsgo's short synonym for `--help`. ttsc owns `--help` / `-h` itself (the
+    // launcher prints its own help), so `-?` is declared as its own tsgo-only
+    // row rather than as an alias — that keeps `ttsc -?` printing tsgo's help
+    // while putting the token inside the schema, where the terminal and
+    // project-free classifications are derived from.
+    name: "-?",
+    kind: "boolean",
+    subcommands: ["ttsc", "build", "check"],
+    consumedBy: ["tsgo"],
+    forwardTo: "tsgo",
+    terminal: true,
+    projectFree: true,
+    description: "Print the tsgo CLI help and exit (forwarded to tsgo).",
+  },
 
   // -------------------------------------------------------------------------
   // `--tsgo-args` — JSON-encoded passthrough envelope the launcher emits on
@@ -512,10 +567,50 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
 ];
 
 /**
- * Lookup of `name` and every alias → its canonical FlagSpec. Built once at
- * module load so the parsing engine has O(1) flag resolution.
+ * Normalize a CLI token to the identity the compiler ttsc wraps resolves it by:
+ * one or two leading dashes removed, the remainder lower-cased.
+ *
+ * TypeScript's option parser — legacy `tsc` and native tsgo alike — strips a
+ * `--` or `-` prefix and matches the rest case-insensitively, so `--noEmit`,
+ * `--noemit`, `--NOEMIT`, and `-noEmit` all name the same option to the tool
+ * ttsc forwards to. The launcher used to key its index on the exact spelling,
+ * so a case variant of a ttsc-owned flag fell through the unknown-flag escape
+ * hatch: tsgo honoured it and every ttsc-side consumer of the same flag never
+ * fired, with no diagnostic.
+ *
+ * This is the single normalization. Everything that resolves a token against
+ * `FLAG_SCHEMA` — the parsing engine, the terminal / shadow / project-free
+ * classifications, and the generated Go allow-lists — keys off this function,
+ * so no two layers can disagree about which flag a spelling names.
+ */
+export function normalizeFlagToken(token: string): string {
+  return token.replace(/^--?/, "").toLowerCase();
+}
+
+/**
+ * Resolve a raw argv token to the flag it names, or `undefined` when the schema
+ * claims no such flag.
+ *
+ * Accepts every spelling the compiler accepts — any casing, one or two leading
+ * dashes — plus the inline `--flag=value` form, whose value is not part of the
+ * identity. A token without a leading dash is never a flag: bare tokens are
+ * input files and flag values, and resolving them here would let a value like
+ * the `all` of `--target all` masquerade as `--all`.
+ */
+export function resolveFlagSpec(token: string): FlagSpec | undefined {
+  if (!token.startsWith("-")) return undefined;
+  const equalsIndex = token.indexOf("=");
+  const name = equalsIndex === -1 ? token : token.slice(0, equalsIndex);
+  return FLAG_BY_TOKEN.get(normalizeFlagToken(name));
+}
+
+/**
+ * Lookup of every declared spelling → its canonical FlagSpec, keyed by
+ * {@link normalizeFlagToken}. Built once at module load so the parsing engine
+ * has O(1) flag resolution. Prefer {@link resolveFlagSpec}, which applies the
+ * normalization for the caller.
  */
-export const FLAG_BY_NAME: ReadonlyMap<string, FlagSpec> = buildFlagIndex();
+export const FLAG_BY_TOKEN: ReadonlyMap<string, FlagSpec> = buildFlagIndex();
 
 function buildFlagIndex(): ReadonlyMap<string, FlagSpec> {
   const index = new Map<string, FlagSpec>();
@@ -530,39 +625,22 @@ function buildFlagIndex(): ReadonlyMap<string, FlagSpec> {
 
 function register(
   index: Map<string, FlagSpec>,
-  key: string,
+  spelling: string,
   flag: FlagSpec,
 ): void {
+  // Two spellings that normalize to one identity would make the schema
+  // ambiguous, so the collision fails loudly at module load rather than
+  // resolving to whichever row was declared last.
+  const key = normalizeFlagToken(spelling);
   const existing = index.get(key);
   if (existing && existing !== flag) {
     throw new Error(
-      `ttsc flag schema: duplicate token ${JSON.stringify(key)} claimed by ${existing.name} and ${flag.name}`,
+      `ttsc flag schema: duplicate token ${JSON.stringify(spelling)} claimed by ${existing.name} and ${flag.name}`,
     );
   }
   index.set(key, flag);
 }
 
-/**
- * Terminal flags as a derived set. Used by `runBuild.ts` to skip the pre-emit
- * pass when one is present.
- */
-export const TERMINAL_FLAGS: ReadonlySet<string> = new Set(
-  FLAG_SCHEMA.flatMap((flag) =>
-    flag.terminal === true ? [flag.name, ...(flag.aliases ?? [])] : [],
-  ),
-);
-
-/**
- * `internalShadow: true` flags as a derived set. Used by `runBuild.ts` to
- * detect a user-forwarded copy of a flag ttsc adds internally so the
- * post-processor does not eat the user's output.
- */
-export const INTERNAL_SHADOW_FLAGS: ReadonlySet<string> = new Set(
-  FLAG_SCHEMA.flatMap((flag) =>
-    flag.internalShadow === true ? [flag.name, ...(flag.aliases ?? [])] : [],
-  ),
-);
-
 /** Tokens (canonical name + aliases) accepted in `subcommand`. */
 export function flagsForSubcommand(subcommand: AnySubcommand): FlagSpec[] {
   return FLAG_SCHEMA.filter((flag) => flag.subcommands.includes(subcommand));
@@ -581,9 +659,13 @@ export function buildGoAllowList(layer: "host" | "lint"): Map<string, boolean> {
     if (!flag.consumedBy.includes(layer)) continue;
     const takesValue = flag.kind === "value" || flag.kind === "valueOptional";
     for (const name of [flag.name, ...(flag.aliases ?? [])]) {
-      const key = name.replace(/^--?/, "");
-      // The Go side strips the leading dashes; if two flags collide on the
-      // stripped key (e.g. `-p` vs `--project`), use the value-taking shape.
+      // Keyed by the one normalization the runtime token lookup uses, so the
+      // generated allow-lists and `resolveFlagSpec` cannot recognise different
+      // spellings. The Go consumers apply the same normalization before the
+      // lookup (`strings.ToLower` on the dash-stripped name).
+      const key = normalizeFlagToken(name);
+      // If two flags collide on the normalized key (e.g. `-p` vs `--project`),
+      // use the value-taking shape.
       const existing = out.get(key);
       if (existing !== undefined && existing !== takesValue) {
         throw new Error(

package/src/internal/assertSafeExplicitCacheDirectory.ts

@@ -0,0 +1,29 @@
+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`,
+    );
+  }
+}