ttsc 0.30.4 → 0.31.0

package/src/flags/parseFlags.ts

@@ -0,0 +1,371 @@
+import type { AnySubcommand } from "./AnySubcommand";
+import type { FlagSpec } from "./FlagSpec";
+import type { ParseOptions } from "./ParseOptions";
+import type { ParseResult } from "./ParseResult";
+import { flagsForSubcommand } from "./flagsForSubcommand";
+import { normalizeFlagToken } from "./normalizeFlagToken";
+import { readCompilerOptionOccurrence } from "./readCompilerOptionOccurrence";
+import { resolveFlagSpec } from "./resolveFlagSpec";
+
+/**
+ * Parse `argv` according to FLAG_SCHEMA filtered by `subcommand`. Returns a
+ * `ParseResult`. Throws `Error` with the configured prefix for a missing
+ * launcher-owned value or a value that fails its validator. Compiler-owned and
+ * unknown options retain their argv spelling for the compiler to diagnose.
+ *
+ * @evidence contracts/common.md#principled-implementation The cursor consumes each argv token at its grammar-owned boundary: launcher schema rows validate local values, compiler arity owns known forwarded values, and entry/separator state preserves program arguments. Canonical flag identities and ordered repetition records retain the command's permitted distinctions.
+ * @evidence contracts/common.md#clear-and-simple-design One parsing loop owns the argv partition while small helpers own value reading, boolean grammar and forwarding arity; all spelling policy comes from normalizeFlagToken instead of parallel case-specific parsers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown options remain native compiler inputs rather than being guessed from particular files. The positional predicate is explicit caller policy, and response-file forwarding follows the compiler's argv contract.
+ * @evidence contracts/common.md#meaningful-documentation The native comment distinguishes local errors from native diagnostics; ParseOptions and ParseResult document separator interaction and argument ownership in separate member paragraphs following the documentation skill.
+ * @evidence contracts/performance.md#efficient-algorithms A monotonically advancing cursor processes N tokens without repeated array shifts; scanning and result storage are O(N) plus visited token/lookahead text and the caller's positional predicate cost. Head and separated remainder each need one invocation snapshot rather than a slice followed by another clone. Building a command's acceptance index scans fixed schema rows and their canonical/alias text once; subsequent invocations reuse it.
+ * @evidence contracts/performance.md#reuse-equivalent-work Launcher acceptance indexes are shared by command identity because module-owned schema rows and normalization policy remain fixed for the loaded module; invocation argv, prefix and classifier stay local and never enter the cached computation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The module retains at most one acceptance index per finite command identity, containing references to fixed schema rows. Each cursor and result collection is invocation-owned and grows with argv size; returning transfers only the result, not the cursor or input copy.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The token-partitioning body reads metadata and argv without directly opening files, resolving paths or calling process APIs. Any native behavior in a supplied positional classifier belongs to that provider; the parser does not certify an arbitrary callback as pure.
+ */
+export function parseFlags(opts: ParseOptions): ParseResult {
+  const accepted = launcherFlagsForSubcommand(opts.subcommand);
+
+  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[] = [];
+
+  // With `forwardAfterFirstPositional`, the separator is read in order rather
+  // than split off first, because only the launcher's own part of argv may
+  // hold it. Everything after the entry belongs to the program, which gets
+  // its own `--` tokens exactly as `node` would hand them over; the one
+  // separator directly after the entry is still consumed, so the documented
+  // `ttsx entry.ts -- --port 3000` passes `--port 3000`.
+  const separatorInOrder =
+    opts.honorDoubleDashSeparator === true &&
+    opts.forwardAfterFirstPositional === true;
+  const separator =
+    opts.honorDoubleDashSeparator === true && !separatorInOrder
+      ? opts.argv.indexOf("--")
+      : -1;
+  let remainder: string[] | null =
+    separator === -1 ? null : opts.argv.slice(separator + 1);
+  const head: ArgvCursor = {
+    tokens: separator === -1 ? [...opts.argv] : opts.argv.slice(0, separator),
+    index: 0,
+  };
+
+  let forwardingTail = false;
+  let entryJustRead = false;
+  while (head.index < head.tokens.length) {
+    const current = head.tokens[head.index++]!;
+    const directlyAfterEntry = entryJustRead;
+    entryJustRead = false;
+    if (separatorInOrder && current === "--") {
+      if (!forwardingTail) {
+        // Before the entry, `--` ends the launcher's options as it always has.
+        remainder = head.tokens.slice(head.index);
+        break;
+      }
+      if (directlyAfterEntry) continue;
+    }
+    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;
+    }
+
+    // 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`, because the lookup is dash- and
+    // case-insensitive.
+    if (current.startsWith("-")) {
+      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(normalizeFlagToken(token));
+      if (flag !== undefined) {
+        consumeFlag(
+          values,
+          repeated,
+          flag,
+          token,
+          inlineValue,
+          head,
+          opts.errorPrefix,
+        );
+        opts.onConsumedFlag?.(
+          flag.name,
+          values.get(flag.name)!,
+          passthrough.length,
+        );
+        continue;
+      }
+
+      const globalFlag = resolveFlagSpec(token);
+      if (globalFlag !== undefined) {
+        forwardKnownButUnaccepted(
+          passthrough,
+          globalFlag,
+          current,
+          inlineValue,
+          head,
+          opts.isPositional,
+        );
+        continue;
+      }
+
+      // The compiler's table owns arity for options the launcher does not own.
+      passthrough.push(current);
+      if (
+        readCompilerOptionOccurrence(head.tokens, head.index - 1).width === 2
+      ) {
+        passthrough.push(head.tokens[head.index++]!);
+      }
+      continue;
+    }
+
+    // Native ignores empty positional tokens; after the entry they remain
+    // program arguments through forwardingTail above.
+    if (current === "") {
+      passthrough.push(current);
+      continue;
+    }
+    if (opts.isPositional !== undefined && !opts.isPositional(current)) {
+      passthrough.push(current);
+      continue;
+    }
+    if (
+      current.startsWith("@") &&
+      (opts.forwardAfterFirstPositional === true ||
+        opts.isPositional !== undefined)
+    ) {
+      passthrough.push(current);
+      continue;
+    }
+    positional.push(current);
+    if (opts.forwardAfterFirstPositional === true && positional.length === 1) {
+      forwardingTail = true;
+      entryJustRead = true;
+    }
+  }
+
+  if (remainder !== null) {
+    const sink = forwardingTail ? tail : passthrough;
+    for (const token of remainder) sink.push(token);
+  }
+
+  return { values, repeated, passthrough, positional, tail };
+}
+
+/** A private token snapshot and the next token to consume. */
+interface ArgvCursor {
+  readonly tokens: readonly string[];
+  index: number;
+}
+
+const launcherFlagsBySubcommand = new Map<
+  AnySubcommand,
+  ReadonlyMap<string, FlagSpec>
+>();
+
+/** Reuse the immutable schema's launcher acceptance index for one command. */
+function launcherFlagsForSubcommand(
+  subcommand: AnySubcommand,
+): ReadonlyMap<string, FlagSpec> {
+  const cached = launcherFlagsBySubcommand.get(subcommand);
+  if (cached !== undefined) return cached;
+  const accepted = new Map<string, FlagSpec>();
+  for (const flag of flagsForSubcommand(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. Filtering on `subcommands` alone
+    // would silently drop every tsgo-only terminal flag at the launcher
+    // boundary.
+    if (!flag.consumedBy.includes("launcher")) continue;
+    accepted.set(normalizeFlagToken(flag.name), flag);
+    for (const alias of flag.aliases ?? []) {
+      accepted.set(normalizeFlagToken(alias), flag);
+    }
+  }
+
+  launcherFlagsBySubcommand.set(subcommand, accepted);
+  return accepted;
+}
+
+/**
+ * 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>,
+  repeated: Map<string, (string | boolean | number)[]>,
+  flag: FlagSpec,
+  token: string,
+  inlineValue: string | undefined,
+  rest: ArgvCursor,
+  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
+      // a recognised literal stays loud: `--singleThreaded=yes` silently
+      // becoming `true` would be a footgun. Mirrors `validatePositiveInt`'s style.
+      const literal = parseBooleanLiteral(inlineValue);
+      if (literal === undefined) {
+        throw new Error(
+          `${errorPrefix} ${token} expects \`true\` or \`false\`, got ${JSON.stringify(
+            inlineValue,
+          )}`,
+        );
+      }
+      record(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.index < rest.tokens.length) {
+      const peek = parseBooleanLiteral(rest.tokens[rest.index]!);
+      if (peek !== undefined) {
+        rest.index++;
+        record(peek);
+        return;
+      }
+    }
+    record(true);
+    return;
+  }
+
+  const raw =
+    inlineValue !== undefined
+      ? inlineValue
+      : takeValueToken(token, rest, errorPrefix);
+  if (flag.validator === "positiveInt") {
+    record(validatePositiveInt(token, raw, errorPrefix));
+    return;
+  }
+  record(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. This is the launcher's own missing-value policy; native scalar
+ * options instead consume a following dash token through the occurrence
+ * reader.
+ */
+function takeValueToken(
+  flag: string,
+  rest: ArgvCursor,
+  errorPrefix: string,
+): string {
+  const value = rest.tokens[rest.index];
+  if (value === undefined) {
+    throw new Error(`${errorPrefix} ${flag} requires a value`);
+  }
+  if (value.startsWith("-")) {
+    throw new Error(
+      `${errorPrefix} ${flag} requires a value (next token ${JSON.stringify(
+        value,
+      )} starts with "-")`,
+    );
+  }
+  rest.index++;
+  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.
+ *
+ * The lexical rule is tsgo's too: it reads a number option with Go's
+ * `strconv.Atoi`, which takes an optional sign and decimal digits only. A
+ * broader JavaScript conversion would turn `1e3`, `0x10`, or `2.0`, which tsgo
+ * rejects, into a different valid worker count.
+ */
+function validatePositiveInt(
+  flag: string,
+  raw: string,
+  errorPrefix: string,
+): number {
+  const value = /^[+-]?[0-9]+$/.test(raw) ? Number(raw) : NaN;
+  if (!Number.isSafeInteger(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 through the
+ * `TTSC_TSGO_ARGS` environment payload); without this branch it would lose the
+ * value token of a `--flag value` pair.
+ *
+ * Native metadata owns whether a following token is consumed. Scalar operands
+ * can include dash prefixes or `.ts` suffixes; `--rootDir src.ts main.ts` has
+ * one option value and one source. List and configuration-only operands retain
+ * their distinct native widths. Schema rows belonging only to another ttsc
+ * layer still consult `isPositional`, because tsgo does not own their arity.
+ */
+function forwardKnownButUnaccepted(
+  passthrough: string[],
+  flag: FlagSpec,
+  original: string,
+  inlineValue: string | undefined,
+  rest: ArgvCursor,
+  isPositional: ((token: string) => boolean) | undefined,
+): void {
+  passthrough.push(original);
+  const native = readCompilerOptionOccurrence(rest.tokens, rest.index - 1);
+  if (native.option !== undefined) {
+    if (native.width === 2) passthrough.push(rest.tokens[rest.index++]!);
+    return;
+  }
+  // Boolean flags carry no required value. `--foo=value` is already one token.
+  if (flag.kind === "boolean" || inlineValue !== undefined) {
+    return;
+  }
+  if (rest.index === rest.tokens.length) return;
+  if (rest.tokens[rest.index]!.startsWith("-")) return;
+  const tsgoOwnsArity =
+    flag.consumedBy.includes("tsgo") || flag.forwardTo === "tsgo";
+  if (
+    tsgoOwnsArity === false &&
+    isPositional !== undefined &&
+    isPositional(rest.tokens[rest.index]!)
+  ) {
+    return;
+  }
+  passthrough.push(rest.tokens[rest.index++]!);
+}

package/src/flags/readCompilerOptionOccurrence.ts

@@ -0,0 +1,107 @@
+import { COMPILER_ENUM_WHITESPACE } from "./COMPILER_ENUM_WHITESPACE";
+import { COMPILER_OPTIONS } from "./COMPILER_OPTIONS";
+import type { CompilerOptionSpec } from "./CompilerOptionSpec";
+import { normalizeFlagToken } from "./normalizeFlagToken";
+
+/**
+ * Read one unexpanded argv frame using pinned native command-line grammar.
+ * Scalars consume dash operands; lists consume only a nonempty parsed list or
+ * its diagnostic, and configuration-only options admit explicit resets.
+ * Response files remain frame boundaries owned by the caller/native parser.
+ *
+ * @evidence contracts/common.md#principled-implementation Generated native kind, element and configuration-only metadata drive scalar, boolean and list lookahead; returned width, optional assignment and deletion-boundary marker retain those distinct decisions. List-level Unicode White_Space follows Go TrimSpace, enum-item emptiness uses the separately generated native IsWhiteSpaceLike set, and rejected inline names remain unknown native options.
+ * @evidence contracts/common.md#clear-and-simple-design One pure occurrence reader owns consumption and assignment; callers advance their own cursor and attach launcher semantics separately. One local record serves classification, forwarding and removal without retaining an argv cursor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Grammar and boundary markers come from native declarations without guessing values from source suffixes, spelling exceptions or treating a dash operand as another launcher request.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the unexpanded-frame scope and distinctions among scalar, list and config-only rules; the private result prose explains removal fences, unknown metadata and absent boolean assignments, while each member documents its role.
+ * @evidence contracts/performance.md#efficient-algorithms Metadata lookup is constant-time after a token-name scan; list lookahead scans its value and components linearly. Temporary component/rune arrays grow with only that value, and callers advance by the returned width.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure lookahead reads current invocation argv; immutable generated tables are already shared by module identity, and no per-argv computation is coordinated or cached here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned occurrence and transient normalized token-name strings, value components and rune arrays belong to this invocation; no argv history, process, handle or persistent invocation state is retained.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This deterministic argv grammar reads generated metadata and Unicode trimming rules without interpreting operands as filesystem paths, expanding response files or probing a native executable; the spawning/compiler owners supply those OS capabilities.
+ */
+export function readCompilerOptionOccurrence(
+  argv: readonly string[],
+  index: number,
+): CompilerOptionOccurrence {
+  const token = argv[index];
+  const option =
+    token?.startsWith("-") === true && !token.includes("=")
+      ? COMPILER_OPTIONS.get(normalizeFlagToken(token))
+      : undefined;
+  if (option === undefined) return { width: 1, needsFence: false };
+  const next = argv[index + 1];
+  if (next === undefined)
+    return {
+      option,
+      width: 1,
+      needsFence: false,
+      booleanValue:
+        option.kind === "boolean" && !option.configOnly ? true : undefined,
+    };
+  if (next === "null")
+    return {
+      option,
+      width: 2,
+      needsFence: false,
+      booleanValue: option.kind === "boolean" ? false : undefined,
+    };
+  if (option.kind === "boolean")
+    return {
+      option,
+      width: next === "true" || next === "false" ? 2 : 1,
+      booleanValue:
+        option.configOnly && next !== "false" ? undefined : next !== "false",
+      needsFence: next.startsWith("-"),
+    };
+  if (option.configOnly)
+    return {
+      option,
+      width: next !== "" && !next.startsWith("-") ? 2 : 1,
+      needsFence: next.startsWith("-"),
+    };
+  if (option.kind === "list") {
+    // Go strings.TrimSpace follows Unicode White_Space, which excludes FEFF
+    // and includes U+0085; JavaScript trim uses a different character set.
+    let start = 0;
+    let end = next.length;
+    const whitespace = /\p{White_Space}/u;
+    while (start < end && whitespace.test(next[start]!)) start++;
+    while (end > start && whitespace.test(next[end - 1]!)) end--;
+    const trimmed = next.slice(start, end);
+    // Enum members undergo the compiler's IsWhiteSpaceLike trim as well;
+    // FEFF and zero-width space can therefore make every member empty.
+    const empty =
+      trimmed === "" ||
+      trimmed.startsWith("-") ||
+      trimmed
+        .split(",")
+        .every((part) =>
+          option.element === "string"
+            ? part === ""
+            : [...part].every((character) =>
+                COMPILER_ENUM_WHITESPACE.has(character),
+              ),
+        );
+    return { option, width: empty ? 1 : 2, needsFence: next.startsWith("-") };
+  }
+  return { option, width: 2, needsFence: false };
+}
+
+/**
+ * One native argv occurrence and the lookahead boundary it establishes.
+ * Undefined metadata denotes a positional token or an unknown option. An
+ * undefined boolean value denotes a nonboolean option or a config-only boolean
+ * request the native compiler rejects without assigning a value.
+ */
+interface CompilerOptionOccurrence {
+  /** Native declaration, absent for non-options and unknown spellings. */
+  readonly option?: CompilerOptionSpec;
+
+  /** Option token plus the next token only when native parsing consumes it. */
+  readonly width: 1 | 2;
+
+  /** Native boolean assignment; false also represents an explicit null reset. */
+  readonly booleanValue?: boolean;
+
+  /** Whether removing the following option requires an empty lookahead fence. */
+  readonly needsFence: boolean;
+}

package/src/flags/readCompilerOptionValues.ts

@@ -0,0 +1,68 @@
+import { normalizeCompilerEnumValue } from "./normalizeCompilerEnumValue";
+import { readCompilerOptionOccurrence } from "./readCompilerOptionOccurrence";
+
+/**
+ * Project visible compiler arguments in native frame order.
+ *
+ * Every frame advances by the owned occurrence reader's consumption width,
+ * including scalars whose values look like flags or response files. Only an
+ * unconsumed response-file token requests native expansion. Known assignments
+ * use canonical option names, and a present null reset is distinct from an
+ * absent assignment. Rejected configuration-only requests make no assignment.
+ * Boolean assignments and enum discriminants are projected for launcher
+ * decisions; other operands retain their forwarded representation. Native
+ * compilation owns full value validation and list conversion.
+ *
+ * @evidence contracts/common.md#principled-implementation Native occurrence widths prevent reinterpreting scalar operands, canonical names retain aliases and order, and explicit null or empty enum assignments remain present resets. Config-only requests without a native boolean assignment do not overwrite earlier values.
+ * @evidence contracts/common.md#clear-and-simple-design One invocation record carries an assignment map and actual response-file frames; callers use map presence for precedence and leave response expansion with the native owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Values remain a launcher projection rather than a fabricated validated configuration; forwarded list operands and unknown native diagnostics are not replaced by guessed schema validation or a response-file parser.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains frame consumption, reset versus absence, assignment admission and validation ownership; the private record's member comments describe the two retained facts.
+ * @evidence contracts/performance.md#efficient-algorithms One advancing cursor projects argv once, with map replacement for repeated assignments; option-name normalization, enum normalization and list lookahead also scan their visited text bytes. The result holds at most the schema's distinct assigned keys plus ordered response-frame references; transient normalized strings/components grow with the current token or operand.
+ * @evidence contracts/performance.md#reuse-equivalent-work Callers share this invocation record across option queries, while immutable native metadata is shared by module identity. No value from a different argv population is reused.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned map and response array transfer to the caller with module-owned canonical keys and current invocation values or normalized enum strings; no process, handle, persistent cache or historical argument population is owned here.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This argv-frame projection treats operands and response requests as data without resolving filesystem paths or reading response contents; expansion, executable discovery and native validation belong to its callers.
+ */
+export function readCompilerOptionValues(
+  argv: readonly string[] = [],
+): CompilerOptionValues {
+  const values = new Map<string, unknown>();
+  const responseFiles: string[] = [];
+  for (let index = 0; index < argv.length; ) {
+    const occurrence = readCompilerOptionOccurrence(argv, index);
+    const option = occurrence.option;
+    const next = argv[index + 1];
+    if (argv[index]!.startsWith("@")) responseFiles.push(argv[index]!);
+    if (option !== undefined) {
+      if (next === "null") values.set(option.name, null);
+      else if (option.kind === "boolean") {
+        if (occurrence.booleanValue !== undefined) {
+          values.set(option.name, occurrence.booleanValue);
+        }
+      } else if (!option.configOnly) {
+        if (option.kind === "list") values.set(option.name, next ?? []);
+        else if (occurrence.width === 2) {
+          values.set(
+            option.name,
+            option.kind === "enum"
+              ? normalizeCompilerEnumValue(next!, "cli")
+              : next,
+          );
+        }
+      }
+    }
+    index += occurrence.width;
+  }
+  return { values, responseFiles };
+}
+
+/** Invocation-local assignments and the unconsumed response expansion requests. */
+interface CompilerOptionValues {
+  /**
+   * Canonical names with last assigned values; map presence retains a null
+   * reset.
+   */
+  readonly values: ReadonlyMap<string, unknown>;
+
+  /** Response-file tokens found at native argv frame boundaries, in their order. */
+  readonly responseFiles: readonly string[];
+}

package/src/flags/resolveFlagSpec.ts

@@ -0,0 +1,29 @@
+import { FLAG_BY_TOKEN } from "./FLAG_BY_TOKEN";
+import type { FlagSpec } from "./FlagSpec";
+import { normalizeFlagToken } from "./normalizeFlagToken";
+
+/**
+ * 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`.
+ *
+ * @evidence contracts/common.md#principled-implementation Requiring a leading dash distinguishes option tokens from values; splitting at the first equals sign and normalizing only the name yields the canonical schema identity while preserving value spelling for its owner.
+ * @evidence contracts/common.md#clear-and-simple-design This resolver owns raw-token classification and delegates spelling policy to normalizeFlagToken and lookup storage to FLAG_BY_TOKEN.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The dash guard follows argv grammar rather than compensating with a list of positional names that happen to collide with options.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain undefined results, inline-value separation and why bare values are rejected, applying the documentation skill's failure-state and rationale guidance.
+ * @evidence contracts/performance.md#efficient-algorithms A dash guard avoids normalization for positional data; locating the first equals sign and normalizing the name scan token bytes linearly before one lookup in the module-built index. Transient name strings grow with the token, without scanning schema rows per request.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transient name strings belong to the invocation; the returned schema reference has module-owned lifetime, and this resolver retains no invocation history or handle.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation-local token interpretation does not coordinate a completed or in-flight producer across requests; callers already share the immutable module-built schema index.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation resolveFlagSpec computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+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));
+}

package/src/index.ts

@@ -2,12 +2,18 @@
  * 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.
+ * and the plugin-author contracts, including passive failure descriptions. CLI
+ * launcher functions, binary resolution, project parsing helpers, and native
+ * build helpers stay off it so the public package surface remains small and
+ * stable.
  */
 
+export * from "./plugin/ITtscCapabilityPlugin";
+export * from "./plugin/CapabilityPluginResolver";
 export * from "./plugin/resolveCapabilityPlugins";
 export * from "./TtscCompiler";
+export * from "./TtscServiceRequestOptions";
 export * from "./TtscService";
 export * from "./structures/index";
+
+export { serializeCompilerError } from "./internal/serializeCompilerError";