ttsc 0.12.3 → 0.13.0

package/src/compiler/internal/runSingleFileEmit.ts

@@ -7,7 +7,16 @@ import { resolveProjectConfig } from "./project/resolveProjectConfig";
 import { resolveEmittedJavaScript } from "./resolveEmittedJavaScript";
 import { runBuild } from "./runBuild";
 
-/** Emit one source file by building its project into a temporary directory. */
+/**
+ * Emit one source file by building its project into a temporary directory.
+ *
+ * The full project is compiled with `forceListEmittedFiles` so that the emitted
+ * file list is available for `resolveEmittedJavaScript`. The temp directory is
+ * always cleaned up in the `finally` block, even on error.
+ *
+ * @returns The transformed JavaScript source text.
+ * @throws When the build exits non-zero or no output is produced for the file.
+ */
 export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const sourceFile = realpathIfExists(
@@ -64,6 +73,10 @@ export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
   }
 }
 
+/**
+ * Resolve symlinks on `file` when it exists; return the original path when the
+ * file is not yet on disk (e.g. a synthetic path used in tests).
+ */
 function realpathIfExists(file: string): string {
   try {
     return fs.realpathSync(file);

package/src/compiler/internal/sharedHostHelpers.ts

@@ -4,9 +4,7 @@ import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoa
  * Reports whether the given transform source is linked into another compiler
  * host instead of owning the process itself.
  */
-export function isLinkedTransform(
-  plugin: ITtscLoadedNativePlugin,
-): boolean {
+export function isLinkedTransform(plugin: ITtscLoadedNativePlugin): boolean {
   return plugin.stage === "transform" && plugin.kind === "linked";
 }
 
@@ -59,12 +57,14 @@ export function assertSharedHostCompatibility(
 export function selectSharedHostPlugin(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): ITtscLoadedNativePlugin {
-  return (
-    plugins.find((plugin) => !isLinkedTransform(plugin)) ??
-    plugins[0]!
-  );
+  return plugins.find((plugin) => !isLinkedTransform(plugin)) ?? plugins[0]!;
 }
 
+/**
+ * Return every plugin whose transform source is linked into another host binary
+ * rather than owning the process. The host binary passes these via
+ * `TTSC_LINKED_PLUGINS_JSON` so their Go code runs inside the same process.
+ */
 export function linkedTransformPlugins(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): ITtscLoadedNativePlugin[] {

package/src/compiler/internal/spawnNative.ts

@@ -0,0 +1,64 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+
+/**
+ * Spawn a native binary (or a Node.js script when the path has a JS/TS
+ * extension) with the given args and return the `spawnSync` result. Sets a
+ * generous 256 MiB output buffer so large projects do not truncate.
+ *
+ * When `options.encoding` is omitted it defaults to `"utf8"`. Pass an explicit
+ * value when the caller needs a different encoding or raw `Buffer` output.
+ */
+export function spawnNative(
+  binary: string,
+  args: readonly string[],
+  options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    encoding?: BufferEncoding;
+  },
+) {
+  const viaNode = /\.(?:[cm]?js|ts)$/i.test(binary);
+  if (!viaNode) {
+    ensureExecutable(binary);
+  }
+  return spawnSync(
+    viaNode ? process.execPath : binary,
+    viaNode ? [binary, ...args] : [...args],
+    {
+      cwd: options.cwd,
+      encoding: options.encoding ?? "utf8",
+      env: options.env,
+      maxBuffer: 1024 * 1024 * 256,
+      windowsHide: true,
+    },
+  );
+}
+
+/**
+ * Ensure the binary has the executable bit set on POSIX systems. Silently skips
+ * on Windows and swallows `chmod` errors to let the original spawn error
+ * surface instead of masking it with a permission error.
+ */
+export 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 {
+    /* keep the original spawn error path */
+  }
+}
+
+/** Coerce a `spawnSync` output value to a plain string, defaulting to `""`. */
+export function outputText(value: string | Buffer | null | undefined): string {
+  if (value == null) {
+    return "";
+  }
+  return typeof value === "string" ? value : value.toString("utf8");
+}

package/src/compiler/internal/transformProjectInMemory.ts

@@ -1,5 +1,3 @@
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
 import path from "node:path";
 
 import {
@@ -12,6 +10,7 @@ import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoa
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
 import { buildNativeCompiler } from "./buildNativeCompiler";
+import { packageRootDir } from "./paths";
 import { readProjectConfig } from "./project/readProjectConfig";
 import { resolveBinary } from "./resolveBinary";
 import { resolveTsgo } from "./resolveTsgo";
@@ -21,8 +20,23 @@ import {
   linkedTransformPlugins,
   selectSharedHostPlugin,
 } from "./sharedHostHelpers";
+import { outputText, spawnNative } from "./spawnNative";
 
-/** Transform a project and capture TypeScript source output in memory. */
+/**
+ * Transform a project and capture TypeScript source output in memory.
+ *
+ * When no plugins are configured the fast path spawns the native ttsc compiler
+ * host (`cmd/ttsc api-transform`) which returns a JSON map of transformed
+ * TypeScript sources. When plugins are present:
+ *
+ * 1. Check-stage plugins run first and abort on failure.
+ * 2. If there are no transform-stage plugins the host is used as the transformer.
+ * 3. If transform plugins exist they are dispatched through the shared-host binary
+ *    with linked plugins passed via `TTSC_LINKED_PLUGINS_JSON`.
+ *
+ * @returns A `{ result, typescript }` pair where `typescript` maps output paths
+ *   to their transformed TypeScript source text.
+ */
 export function transformProjectInMemory(options: ITtscCompilerContext): {
   result: TtscBuildResult;
   typescript: Record<string, string>;
@@ -39,6 +53,7 @@ export function transformProjectInMemory(options: ITtscCompilerContext): {
   return transformProjectWithNativeHost(options, project);
 }
 
+/** Return true when the project or the call-level options declare any plugins. */
 function hasConfiguredPlugins(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -46,6 +61,11 @@ function hasConfiguredPlugins(
   return hasProjectPluginEntries(project, options.plugins);
 }
 
+/**
+ * Transform via the built-in native compiler host (`cmd/ttsc api-transform`).
+ * Used when no user plugins are configured, or as the fallback transformer when
+ * check-stage plugins pass and no transform-stage plugins are declared.
+ */
 function transformProjectWithNativeHost(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -160,6 +180,10 @@ function transformProjectWithPlugins(
   };
 }
 
+/**
+ * Run every check-stage plugin in sequence, short-circuiting on the first
+ * failure. Returns the aggregated `TtscBuildResult` (status 0 when all pass).
+ */
 function runNativeChecks(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
@@ -204,6 +228,7 @@ function runNativeChecks(
   return result;
 }
 
+/** Build the CLI argument list for the `transform` subcommand. */
 function createNativeTransformArgs(
   project: ITtscParsedProjectConfig,
   plugins: readonly ITtscLoadedNativePlugin[],
@@ -216,6 +241,7 @@ function createNativeTransformArgs(
   ];
 }
 
+/** Build the CLI argument list for the `check` subcommand. */
 function createNativeCheckArgs(
   project: ITtscParsedProjectConfig,
   plugins: readonly ITtscLoadedNativePlugin[],
@@ -228,6 +254,10 @@ function createNativeCheckArgs(
   ];
 }
 
+/**
+ * Serialize the plugin list to a JSON string for `--plugins-json=`. Only the
+ * fields the native binary needs are included to keep the arg short.
+ */
 function serializeNativePlugins(
   plugins: readonly ITtscLoadedNativePlugin[],
 ): string {
@@ -240,6 +270,12 @@ function serializeNativePlugins(
   );
 }
 
+/**
+ * Build the environment for a native plugin spawn. Injects `TTSC_NODE_BINARY`,
+ * `TTSC_TSGO_BINARY`, and `TTSC_TTSX_BINARY` so the sidecar can re-invoke
+ * Node.js or tsgo without searching PATH. For transform plugins, also passes
+ * `TTSC_LINKED_PLUGINS_JSON` when linked sources are present.
+ */
 function nativePluginEnv(
   options: ITtscCompilerContext,
   projectRoot: string,
@@ -265,53 +301,13 @@ function nativePluginEnv(
   return env;
 }
 
-function spawnNative(
-  binary: string,
-  args: readonly string[],
-  options: {
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-  },
-) {
-  const viaNode = /\.(?:[cm]?js|ts)$/i.test(binary);
-  if (!viaNode) {
-    ensureExecutable(binary);
-  }
-  return spawnSync(
-    viaNode ? process.execPath : binary,
-    viaNode ? [binary, ...args] : [...args],
-    {
-      cwd: options.cwd,
-      encoding: "utf8",
-      env: options.env,
-      maxBuffer: 1024 * 1024 * 256,
-      windowsHide: true,
-    },
-  );
-}
-
-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 {
-    /* keep the original spawn error path */
-  }
-}
-
-function outputText(value: string | Buffer | null | undefined): string {
-  if (value == null) {
-    return "";
-  }
-  return typeof value === "string" ? value : value.toString("utf8");
-}
-
+/**
+ * Parse the JSON envelope written by the native transform host to stdout.
+ *
+ * The `typescript` field must be a `Record<string, string>`. Any other shape is
+ * treated as a protocol error and throws with the stderr/stdout context. JSON
+ * parse errors are also wrapped with the same context message.
+ */
 function parseNativeTransformOutput(
   stdout: string,
   stderr: string,
@@ -344,6 +340,7 @@ function parseNativeTransformOutput(
   }
 }
 
+/** Type guard: true when `value` is a non-null, non-array object of strings. */
 function isTextRecord(value: unknown): value is Record<string, string> {
   return (
     typeof value === "object" &&
@@ -352,20 +349,3 @@ function isTextRecord(value: unknown): value is Record<string, string> {
     Object.values(value).every((entry) => typeof entry === "string")
   );
 }
-
-function packageRootDir(): string {
-  let current = path.resolve(__dirname);
-  while (true) {
-    if (
-      fs.existsSync(path.join(current, "package.json")) &&
-      fs.existsSync(path.join(current, "go.mod"))
-    ) {
-      return fs.realpathSync.native?.(current) ?? fs.realpathSync(current);
-    }
-    const parent = path.dirname(current);
-    if (parent === current) {
-      throw new Error("ttsc: package root not found for native compiler build");
-    }
-    current = parent;
-  }
-}

package/src/flags/parser.ts

@@ -0,0 +1,367 @@
+// Schema-driven CLI parser used by both `runTtsc.ts` and `runTtsx.ts`.
+//
+// One engine, one schema. Each subcommand picks the subset of FLAG_SCHEMA it
+// accepts and feeds it through `parseFlags`. The engine returns:
+//
+//   * `values`      — typed values for every consumed flag.
+//   * `passthrough` — flags ttsc did not consume but must forward verbatim
+//                     to tsgo (or to native sidecars via `--tsgo-args`).
+//   * `positional`  — bare non-flag tokens (file paths, entry files, …).
+//
+// 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";
+
+/**
+ * Per-subcommand parse result. `values` is keyed by the canonical flag
+ * name (e.g. `"--singleThreaded"`); boolean flags resolve to `true`/`false`,
+ * value flags to the parsed value type. Callers narrow with the helpers
+ * below (`getBoolean`, `getString`, `getNumber`).
+ */
+export interface ParseResult {
+  /** Canonical flag name → resolved value. */
+  readonly values: ReadonlyMap<string, string | boolean | number>;
+  /** Flags the engine did not consume — forwarded to tsgo. */
+  readonly passthrough: readonly string[];
+  /** Bare non-flag positional arguments, in original order. */
+  readonly positional: readonly string[];
+  /**
+   * Tokens that arrived after the `forwardAfterFirstPositional` sentinel.
+   * These are intended for the user's program (e.g. ttsx's entry-file argv);
+   * they are NOT forwarded to tsgo. Always empty when
+   * `forwardAfterFirstPositional` is false.
+   */
+  readonly tail: readonly string[];
+}
+
+/**
+ * Options controlling a single `parseFlags` invocation.
+ */
+export interface ParseOptions {
+  /** Which subcommand's flag subset to accept. */
+  readonly subcommand: AnySubcommand;
+  /** Argv tail (the launcher has already split off the subcommand). */
+  readonly argv: readonly string[];
+  /**
+   * Error prefix used when the parser throws (`"ttsc:"` or `"ttsx:"`). The
+   * engine itself is product-neutral; the caller controls the brand.
+   */
+  readonly errorPrefix: string;
+  /**
+   * `true` to treat the FIRST positional token as a sentinel that switches
+   * the engine to "forward everything after" mode (ttsx's entry-file
+   * behaviour: tokens after the entry are runtime argv, not tsgo flags).
+   * The sentinel itself is still recorded as a positional argument.
+   */
+  readonly forwardAfterFirstPositional?: boolean;
+  /**
+   * Optional `"--"` separator handling: when present in argv, every token
+   * after `--` is appended to `passthrough` as-is (ttsx already does this).
+   */
+  readonly honorDoubleDashSeparator?: boolean;
+}
+
+/**
+ * Parse `argv` according to FLAG_SCHEMA filtered by `subcommand`. Returns a
+ * `ParseResult`. Throws `Error` (with the configured prefix) on invalid
+ * input — unknown subcommand-only flag, missing required value, value that
+ * fails its validator.
+ */
+export function parseFlags(opts: ParseOptions): ParseResult {
+  const accepted = new Map<string, FlagSpec>();
+  for (const flag of flagsForSubcommand(opts.subcommand)) {
+    // A flag enters the launcher's `accepted` set only when its
+    // `consumedBy` includes `"launcher"`. Flags consumed solely by tsgo
+    // or by native sidecars (e.g. `--showConfig`, `--listFilesOnly`)
+    // must fall through to `forwardKnownButUnaccepted` so the launcher
+    // forwards them verbatim instead of storing them in `values` where
+    // no consumer reads them back out. The previous shape — filter on
+    // `subcommands` only — silently dropped every tsgo-only terminal
+    // 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);
+  }
+
+  const values = new Map<string, string | boolean | number>();
+  const passthrough: string[] = [];
+  const positional: string[] = [];
+  const tail: string[] = [];
+
+  let remainder: string[] | null = null;
+  if (opts.honorDoubleDashSeparator === true) {
+    const separator = opts.argv.indexOf("--");
+    if (separator !== -1) {
+      remainder = [...opts.argv.slice(separator + 1)];
+    }
+  }
+  const head: string[] = [
+    ...(remainder === null ? opts.argv : opts.argv.slice(0, indexOfSeparator(opts.argv))),
+  ];
+
+  let forwardingTail = false;
+  while (head.length !== 0) {
+    const current = head.shift()!;
+    if (forwardingTail) {
+      // Post-sentinel tokens belong to the user's program (e.g. the typia.ts
+      // entry's own argv: `ttsx typia.ts generate --input X`). They MUST NOT
+      // be forwarded to tsgo — the caller distinguishes `tail` from
+      // `passthrough` so script args never reach tsgo's option parser.
+      tail.push(current);
+      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);
+
+    const flag = accepted.get(token);
+    if (flag !== undefined) {
+      consumeFlag(values, 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;
+    }
+
+    // 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("-")) {
+      passthrough.push(current);
+      continue;
+    }
+
+    // Bare token: positional argument (file / entry / project path).
+    positional.push(current);
+    if (
+      opts.forwardAfterFirstPositional === true &&
+      positional.length === 1
+    ) {
+      forwardingTail = true;
+    }
+  }
+
+  if (remainder !== null) {
+    // `--` separator: everything after goes to the user program when we are
+    // in tail mode (ttsx after the entry), otherwise to tsgo as passthrough.
+    const sink = forwardingTail ? tail : passthrough;
+    for (const token of remainder) sink.push(token);
+  }
+
+  return { values, passthrough, positional, tail };
+}
+
+/**
+ * Pull the value for `flag` from either `inlineValue` (`--flag=value`) or
+ * the next argv token (`--flag value`), validate it per the schema, and
+ * write it to the result map.
+ */
+function consumeFlag(
+  values: Map<string, string | boolean | number>,
+  flag: FlagSpec,
+  token: string,
+  inlineValue: string | undefined,
+  rest: string[],
+  errorPrefix: string,
+): void {
+  if (flag.kind === "boolean") {
+    if (inlineValue !== undefined) {
+      // `--flag=false` / `--flag=true` inline form. Anything other than
+      // a recognised literal stays loud: `--singleThreaded=yes` silently
+      // becoming `true` is the kind of footgun the RCA's RC-4 class
+      // covers. Mirrors `validatePositiveInt`'s style.
+      const literal = parseBooleanLiteral(inlineValue);
+      if (literal === undefined) {
+        throw new Error(
+          `${errorPrefix} ${token} expects \`true\` or \`false\`, got ${JSON.stringify(
+            inlineValue,
+          )}`,
+        );
+      }
+      values.set(flag.name, literal);
+      return;
+    }
+    // Space form `--flag true` / `--flag false`: peek the next token and
+    // consume it only when it parses as a boolean literal. tsgo accepts
+    // this shape natively; the launcher must mirror it so `ttsc --noEmit
+    // false` does not corrupt argv (positional sink getting `false`,
+    // tsgo seeing it as a stray input file).
+    if (rest.length > 0) {
+      const peek = parseBooleanLiteral(rest[0]!);
+      if (peek !== undefined) {
+        rest.shift();
+        values.set(flag.name, peek);
+        return;
+      }
+    }
+    values.set(flag.name, true);
+    return;
+  }
+
+  const raw =
+    inlineValue !== undefined ? inlineValue : takeValueToken(token, rest, errorPrefix);
+  if (flag.validator === "positiveInt") {
+    values.set(flag.name, validatePositiveInt(token, raw, errorPrefix));
+    return;
+  }
+  values.set(flag.name, raw);
+}
+
+/**
+ * Read the value token that follows `flag`. Throws if argv ends here OR if
+ * the next token looks like another flag (`-` prefix). Without the
+ * "looks like a flag" guard `ttsc --cwd --strict src/main.ts` would silently
+ * consume `--strict` as the value of `--cwd`, leaving `--strict` lost and
+ * `cwd` set to a junk path. Mirrors the symmetric guard already in
+ * `forwardKnownButUnaccepted` (RC-1 fairness — the two value-resolution
+ * paths must agree on what counts as "a missing value").
+ */
+function takeValueToken(
+  flag: string,
+  rest: string[],
+  errorPrefix: string,
+): string {
+  const value = rest.shift();
+  if (value === undefined) {
+    throw new Error(`${errorPrefix} ${flag} requires a value`);
+  }
+  if (value.startsWith("-")) {
+    // Put it back so the next loop iteration parses it as its own flag.
+    rest.unshift(value);
+    throw new Error(
+      `${errorPrefix} ${flag} requires a value (next token ${JSON.stringify(
+        value,
+      )} starts with "-")`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Parse a CLI boolean literal — `true`/`false` only (case-sensitive to
+ * match tsgo's parser). Returns `undefined` for any other token so the
+ * caller knows to throw or treat as a non-value.
+ */
+function parseBooleanLiteral(raw: string): boolean | undefined {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  return undefined;
+}
+
+/**
+ * Validate a `positiveInt` value. Mirrors tsgo's `--checkers minValue:1`
+ * constraint so a typo fails loudly at the launcher rather than reaching
+ * tsgo with an invalid argument.
+ */
+function validatePositiveInt(
+  flag: string,
+  raw: string,
+  errorPrefix: string,
+): number {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(
+      `${errorPrefix} ${flag} expects a positive integer, got ${JSON.stringify(raw)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Forward a flag the schema knows about but the current subcommand does
+ * not 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.
+ */
+function forwardKnownButUnaccepted(
+  passthrough: string[],
+  flag: FlagSpec,
+  original: string,
+  inlineValue: string | undefined,
+  rest: string[],
+): void {
+  passthrough.push(original);
+  // Boolean flags carry no value. `--foo=value` already encodes the value
+  // inline. Otherwise the next argv token is the flag's value: keep it
+  // adjacent so tsgo receives the pair intact.
+  if (flag.kind === "boolean" || inlineValue !== undefined) {
+    return;
+  }
+  if (rest.length === 0) return;
+  if (rest[0]!.startsWith("-")) return;
+  passthrough.push(rest.shift()!);
+}
+
+/**
+ * Return the index of the `--` separator in `argv`, or `argv.length` when
+ * absent. The parser slices on this index when honorDoubleDashSeparator.
+ */
+function indexOfSeparator(argv: readonly string[]): number {
+  const index = argv.indexOf("--");
+  return index === -1 ? argv.length : index;
+}
+
+// -----------------------------------------------------------------------------
+// Typed accessors. The parser stores raw values (string | boolean | number) so
+// the engine stays untyped; callers pick the shape per flag.
+// -----------------------------------------------------------------------------
+
+/** Return the boolean value of `flag` or `undefined` if not present. */
+export function getBoolean(
+  result: ParseResult,
+  flag: string,
+): boolean | undefined {
+  const value = result.values.get(flag);
+  if (typeof value === "boolean") return value;
+  return undefined;
+}
+
+/** Return the string value of `flag` or `undefined` if not present. */
+export function getString(
+  result: ParseResult,
+  flag: string,
+): string | undefined {
+  const value = result.values.get(flag);
+  if (typeof value === "string") return value;
+  return undefined;
+}
+
+/** Return the numeric value of `flag` or `undefined` if not present. */
+export function getNumber(
+  result: ParseResult,
+  flag: string,
+): number | undefined {
+  const value = result.values.get(flag);
+  if (typeof value === "number") return value;
+  return undefined;
+}
+
+/** Marker type so docs callers can name the validator without an import dance. */
+export type { ValueValidator };