ttsc 0.30.4 → 0.31.0

package/src/flags/{schema.ts → FLAG_SCHEMA.ts}

@@ -1,189 +1,26 @@
-// SOURCE-OF-TRUTH FLAG SCHEMA for the ttsc / ttsx command-line surface.
-//
-// One declaration per flag, consumed by every layer that needs to know about
-// the flag:
-//
-//   * `packages/ttsc/src/flags/parser.ts`    — runtime TS parsing engine used
-//                                              by `runTtsc.ts` and `runTtsx.ts`.
-//   * `packages/ttsc/scripts/gen-flags.cjs`  — codegen that emits Go
-//                                              allow-lists and the docs table.
-//   * `packages/ttsc/cmd/ttsc/flags_gen.go`  — generated Go allow-list shared
-//                                              by `cmd/ttsc/*.go` and
-//                                              `utility/host.go`.
-//   * `packages/lint/linthost/flags_gen.go`  — generated Go allow-list shared
-//                                              by lint subcommand parsers.
-//   * `website/src/content/docs/ttsc/flags.mdx` — generated reference table.
-//
-// The generator runs from `pnpm format`; its committed output is the spec the
-// Go side reads, just like the `gen_shims:hand-maintained` pattern from
-// AGENTS.md §2.1. Editing the generated files by hand is rejected by the
-// `format` check.
+import type { FlagSpec } from "./FlagSpec";
 
 /**
- * Subcommands the ttsc CLI dispatches to. The bare `"ttsc"` entry covers the
- * default lane (no explicit subcommand, e.g. `ttsc -p tsconfig.json`).
- */
-export type TtscSubcommand =
-  | "ttsc"
-  | "build"
-  | "cache"
-  | "check"
-  | "fix"
-  | "format"
-  | "prepare"
-  | "clean";
-
-/**
- * Subcommands the ttsx CLI dispatches to. ttsx exposes a single lane today but
- * the schema mirrors ttsc's shape so future subcommands plug in without a
- * second engine.
- */
-export type TtsxSubcommand = "ttsx";
-
-export type AnySubcommand = TtscSubcommand | TtsxSubcommand;
-
-/**
- * Layers a flag can be consumed by. The order reflects the runtime pipeline:
+ * Shared routing schema for flags ttsc / ttsx consumes, classifies or shadows.
+ * Unknown compiler options can still be forwarded without a schema row. Runtime
+ * parsing reads this table; generation emits native allow-lists and
+ * documentation, while pinned native declarations supply compiler grammar.
  *
- * Launcher → runBuild → tsgo / native sidecars (host, lint).
+ * One declaration per flag, consumed by every layer that needs to know about
+ * it:
  *
- * A flag must declare at least one consumer. `forwardTo` declares where the
- * flag travels when the consuming layer does not absorb it (e.g. ttsc-owned
- * flags that the JS launcher consumes and re-emits as different tsgo flags).
- */
-export type FlagLayer =
-  | "launcher" // JS layer (`runTtsc.ts` / `runTtsx.ts`)
-  | "runBuild" // JS layer (`runBuild.ts`) — internally adds the flag to tsgo
-  | "tsgo" // tsgo binary (TypeScript-Go option parser)
-  | "host" // native shared host (`utility/host.go`, `cmd/ttsc/build.go`)
-  | "lint"; // native lint subcommand (`packages/lint/linthost/*.go`)
-
-/**
- * Argument shape of a flag.
+ * - `packages/ttsc/src/flags/parseFlags.ts`: the runtime parsing engine behind
+ *   `runTtsc` and `runTtsx`.
+ * - `packages/ttsc/scripts/gen-flags.mts`: the generator that emits the Go
+ *   allow-lists and the docs table below.
+ * - `packages/ttsc/cmd/ttsc/flags_gen.go` and
+ *   `packages/ttsc/utility/flags_gen.go`: the generated host allow-list.
+ * - `packages/lint/linthost/flags_gen.go`: the generated lint allow-list.
+ * - `website/src/content/docs/ttsc/flags.mdx`: the generated reference table.
  *
- * - `boolean` — `--flag` with an optional spaced `true` / `false`. Launcher flags
- *   also accept `--flag=true` / `--flag=false`; tsgo-forwarded flags stay
- *   verbatim because pinned tsgo does not split `=`.
- * - `value` — `--flag value`. Launcher flags also accept `--flag=value`.
- * - `valueOptional` — `--flag` standalone is allowed; if followed by a non-flag
- *   token that token is consumed as the value. (Currently unused — declared for
- *   future flags like `--watch [path]`.)
- */
-export type FlagKind = "boolean" | "value" | "valueOptional";
-
-/**
- * Validation predicate for `value`-kind flags. `none` is the default (accept
- * any string).
- */
-export type ValueValidator = "none" | "positiveInt";
-
-/**
- * One CLI flag's complete contract. Every layer's behaviour is structural —
- * which subcommands accept the flag, where it is consumed, where it is
- * forwarded, whether it is terminal (prints and exits) — so the next layer
- * never silently drops the flag.
- */
-export interface FlagSpec {
-  /**
-   * Canonical flag name including leading dashes (`"--singleThreaded"`). The
-   * generator uses this as the map key in the Go allow-list and as the first
-   * column of the docs table.
-   */
-  readonly name: string;
-
-  /**
-   * Alternative spellings (`"-p"`, `"--project"` for `--tsconfig`). The parsing
-   * engine treats every alias as an equivalent of `name`.
-   */
-  readonly aliases?: readonly string[];
-
-  /** Argument shape: boolean / required value / optional value. */
-  readonly kind: FlagKind;
-
-  /**
-   * For `value` flags: optional validator. `positiveInt` mirrors the
-   * `--checkers minValue:1` constraint tsgo enforces.
-   */
-  readonly validator?: ValueValidator;
-
-  /** Subcommands that accept this flag. */
-  readonly subcommands: readonly AnySubcommand[];
-
-  /**
-   * Layers that read the flag into a typed option. Order matters only for
-   * documentation; the parsing engine merges across layers.
-   */
-  readonly consumedBy: readonly FlagLayer[];
-
-  /**
-   * Where the flag travels when the consuming layer does not absorb it. Default
-   * for any flag a layer does not consume is `"tsgo"` — i.e. the launcher
-   * forwards an unknown flag to tsgo via passthrough. Setting this to
-   * `undefined` while `consumedBy: ["launcher"]` is set means the flag is
-   * intentionally consumed-not-forwarded (e.g. ttsc-internal `--binary`).
-   */
-  readonly forwardTo?: FlagLayer;
-
-  /**
-   * Terminal flags ask the underlying tool to print something and exit
-   * (`--help`, `--version`, `--showConfig`, `--listFilesOnly`, `--all`,
-   * `--init`). ttsc must not wrap them in a pre-emit pass — that is how the
-   * `--showConfig prints twice` bug appeared (RC-2).
-   */
-  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
-   * user-visible behaviour (no double-print, no swallowed output). The shadow
-   * check is structural rather than `passthrough.includes("…")`.
-   *
-   * Currently true for `--listEmittedFiles`, `--noEmit`, `--pretty`.
-   */
-  readonly internalShadow?: boolean;
-
-  /**
-   * `true` when pinned tsgo only permits the option in tsconfig, except for
-   * command-line `false` or `null`. The launcher forwards the original argv so
-   * tsgo remains the diagnostic authority.
-   */
-  readonly tsconfigOnly?: boolean;
-
-  /**
-   * Native sidecar capability that must be declared before ttsc sends this flag
-   * as a bare CLI argument. Everything else routes through `--tsgo-args` or
-   * stays in the JS launcher.
-   */
-  readonly nativeCapability?: "diagnosticsTiming" | "threadingArgs";
-
-  /** Human description for `--help` and the docs table. */
-  readonly description: string;
-}
-
-/**
- * Single source of truth for every flag the ttsc / ttsx CLI accepts. New flags
- * are added here and only here; the generator rebuilds the parsers and the Go
- * allow-lists from this table.
+ * The generator runs from `pnpm format`, and its committed output is the spec
+ * the Go side reads. Editing a generated file by hand is rejected by the
+ * `check:flags` drift check.
  *
  * Constraints enforced by the parser and the generator:
  *
@@ -192,9 +29,9 @@ export interface FlagSpec {
  * 2. A flag listed in `consumedBy: ["launcher"]` without a `forwardTo`
  *    consumes-not-forwards. The generator flags this in the docs and the Go
  *    allow-list so the boundary is explicit.
- * 3. A flag with `subcommands` covering `clean` or `prepare` is parsed by the
- *    project-args lane; the parsing engine accepts the same flag in build /
- *    check / fix / format without a separate parser.
+ * 3. The project-args and build lanes use the same parsing engine, but each
+ *    command accepts only rows whose `subcommands` include its identity and
+ *    whose `consumedBy` includes the launcher.
  */
 export const FLAG_SCHEMA: readonly FlagSpec[] = [
   // -------------------------------------------------------------------------
@@ -223,14 +60,16 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
   // Solution build mode — declared so the launcher can refuse it in its own
   // voice instead of forwarding it.
   //
-  // `createTsgoBuildArgs` opens the forwarded argv with `-p <tsconfig>` because
+  // Project-dependent `createTsgoBuildArgs` opens forwarded argv with `-p`
+  // and the selected config because
   // ttsc resolves the project itself (extends chains, plugin config discovery,
-  // cache keys, resident session identity) and pins the result. A forwarded
-  // `--build` therefore always lands after `-p`, and tsgo answers with TS6369
+  // cache keys, resident session identity) and pins the result. In that lane,
+  // a forwarded `--build` lands after `-p`, and tsgo answers with TS6369
   // "Option '--build' must be the first command line argument" — a diagnostic
   // that contradicts the command line the user actually typed. ttsc's plugin,
   // cache, and emit architecture is built around one resolved project, so
-  // solution mode is unsupported rather than merely misordered.
+  // solution mode is unsupported rather than merely misordered. The separate
+  // project-free terminal branch does not first resolve or inject a project.
   // -------------------------------------------------------------------------
   {
     name: "--build",
@@ -297,7 +136,7 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
     subcommands: ["ttsc", "build", "check"],
     consumedBy: ["launcher", "runBuild", "host", "lint"],
     internalShadow: true,
-    description: "Force analysis-only build with no file writes.",
+    description: "Force analysis-only build without emitted compiler outputs.",
   },
   {
     name: "--outDir",
@@ -532,8 +371,8 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
 
   // -------------------------------------------------------------------------
   // tsgo-internal flags ttsc adds itself; users may also forward them.
-  // Declaring them keeps the launcher's parser from treating them as
-  // unknown forwarded flags whose value token gets misclassified.
+  // Their schema identities support shadow/terminal classification; pinned
+  // native occurrence metadata owns forwarded value-token consumption.
   // -------------------------------------------------------------------------
   {
     name: "--listEmittedFiles",
@@ -546,12 +385,10 @@ 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.
+    // Pinned native occurrence metadata owns boolean lookahead, including a
+    // following literal `true`, `false` or `null`. The schema's kind must still
+    // agree with native declarations for generation checks and derived views;
+    // the current forwarding cursor does not infer native arity from this row.
     name: "--pretty",
     kind: "boolean",
     subcommands: ["ttsc", "ttsx", "build", "check", "fix", "format"],
@@ -636,16 +473,16 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
 
   // -------------------------------------------------------------------------
   // `--tsgo-args` — JSON-encoded passthrough envelope a native sidecar decodes
-  // back into the tsgo argv. Listed here so the schema describes every flag
-  // the Go layers accept, not just the user-facing ones.
+  // back into the tsgo argv. Public and shared transport fields appear here;
+  // native commands may additionally declare private protocol fields locally.
   //
-  // The launcher no longer emits it. A CLI flag is fatal to any host whose
-  // `flag.FlagSet` does not declare it, and this one was added to a plugin
-  // protocol third-party hosts had already frozen, so every forwarded compiler
-  // flag exited 2 on a typia/nestia-shaped sidecar (issue #1188). The payload
-  // now rides the `TTSC_TSGO_ARGS` environment variable, which an unaware host
-  // simply ignores. ttsc's own hosts still accept the flag so an older
-  // launcher, or an embedder that composes sidecar argv itself, keeps working.
+  // The launcher does not emit it. A CLI flag is fatal to any host whose
+  // `flag.FlagSet` does not declare it, and third-party hosts have a frozen
+  // plugin protocol, so forwarding compiler flags that way would exit 2 on a
+  // typia/nestia-shaped sidecar. The payload rides the
+  // `TTSC_TSGO_ARGS` environment variable, which an unaware host simply
+  // ignores. ttsc's own hosts still accept the flag so an older launcher, or an
+  // embedder that composes sidecar argv itself, keeps working.
   // -------------------------------------------------------------------------
   {
     name: "--tsgo-args",
@@ -704,115 +541,3 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
       "Write transform output to PATH (lint transform only; default: stdout).",
   },
 ];
-
-/**
- * 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_TOKEN: ReadonlyMap<string, FlagSpec> = buildFlagIndex();
-
-function buildFlagIndex(): ReadonlyMap<string, FlagSpec> {
-  const index = new Map<string, FlagSpec>();
-  for (const flag of FLAG_SCHEMA) {
-    register(index, flag.name, flag);
-    for (const alias of flag.aliases ?? []) {
-      register(index, alias, flag);
-    }
-  }
-  return index;
-}
-
-function register(
-  index: Map<string, FlagSpec>,
-  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(spelling)} claimed by ${existing.name} and ${flag.name}`,
-    );
-  }
-  index.set(key, flag);
-}
-
-/** Tokens (canonical name + aliases) accepted in `subcommand`. */
-export function flagsForSubcommand(subcommand: AnySubcommand): FlagSpec[] {
-  return FLAG_SCHEMA.filter((flag) => flag.subcommands.includes(subcommand));
-}
-
-/**
- * Allow-list map for the Go layer named `layer` (`"host"` or `"lint"`):
- * flag-name (no leading dashes) → whether the flag takes a value token. The
- * generator emits a literal Go map with the same shape, but this function is
- * the runtime equivalent — used in tests to verify the generated Go matches the
- * schema.
- */
-export function buildGoAllowList(layer: "host" | "lint"): Map<string, boolean> {
-  const out = new Map<string, boolean>();
-  for (const flag of FLAG_SCHEMA) {
-    if (!flag.consumedBy.includes(layer)) continue;
-    const takesValue = flag.kind === "value" || flag.kind === "valueOptional";
-    for (const name of [flag.name, ...(flag.aliases ?? [])]) {
-      // 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(
-          `ttsc flag schema: conflicting Go allow-list entry for ${JSON.stringify(key)} on layer ${layer}`,
-        );
-      }
-      out.set(key, takesValue);
-    }
-  }
-  return out;
-}

package/src/flags/FlagKind.ts

@@ -0,0 +1,22 @@
+/**
+ * Argument shape of a flag.
+ *
+ * - `boolean` — `--flag` with an optional spaced `true` / `false`. Launcher flags
+ *   also accept `--flag=true` / `--flag=false`; tsgo-forwarded flags stay
+ *   verbatim because pinned tsgo does not split `=`.
+ * - `value` — `--flag value`. Launcher flags also accept `--flag=value`.
+ * - `valueOptional` — reserved optional-value shape. No current schema row uses
+ *   it, and the launcher consumption helper does not implement a standalone
+ *   optional-value branch. This literal does not advertise an active CLI
+ *   feature.
+ *
+ * @evidence contracts/common.md#principled-implementation The active schema's boolean and value rows are parsed locally when launcher-owned, while compiler-owned spellings retain native parser semantics. valueOptional remains an unused vocabulary member without a launcher consumption branch.
+ * @evidence contracts/common.md#clear-and-simple-design Arity belongs to each FlagSpec through one small vocabulary instead of being inferred independently by every forwarding layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The documented distinction between launcher equals forms and native verbatim forwarding follows the pinned compiler's option grammar rather than patching its parser.
+ * @evidence contracts/common.md#meaningful-documentation The native bullet list explains each arity and the equals-form boundary; it explicitly identifies the unused optional-value shape rather than implying an active CLI feature.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export type FlagKind = "boolean" | "value" | "valueOptional";

package/src/flags/FlagLayer.ts

@@ -0,0 +1,24 @@
+/**
+ * Layers a flag can be consumed by. The order reflects the runtime pipeline:
+ *
+ * Launcher → runBuild → tsgo / native sidecars (host, lint).
+ *
+ * A flag must declare at least one consumer. `forwardTo` declares where the
+ * flag travels when the consuming layer does not absorb it (e.g. ttsc-owned
+ * flags that the JS launcher consumes and re-emits as different tsgo flags).
+ *
+ * @evidence contracts/common.md#principled-implementation These literals identify actual consumers in the launcher, build coordinator, native compiler and plugin hosts; consumedBy and forwardTo can therefore express ownership separately from transport.
+ * @evidence contracts/common.md#clear-and-simple-design One shared vocabulary records the pipeline boundaries while FlagSpec owns per-flag routing, avoiding independent layer-specific interpretations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Host and lint identities name supported native boundaries; their fixed spellings are schema discriminants rather than fixture-dependent routing.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains pipeline order and consumption versus forwarding, with inline member context identifying the implementation owners in accordance with the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export type FlagLayer =
+  | "launcher" // JS layer (`runTtsc.ts` / `runTtsx.ts`)
+  | "runBuild" // JS layer (`compiler/internal/build`) — internally adds the flag to tsgo
+  | "tsgo" // tsgo binary (TypeScript-Go option parser)
+  | "host" // native shared host (`utility/host.go`, `cmd/ttsc/build.go`)
+  | "lint";

package/src/flags/FlagSpec.ts

@@ -0,0 +1,118 @@
+import type { AnySubcommand } from "./AnySubcommand";
+import type { FlagKind } from "./FlagKind";
+import type { FlagLayer } from "./FlagLayer";
+import type { ValueValidator } from "./ValueValidator";
+
+/**
+ * One CLI flag's complete contract. Every layer's behaviour is structural —
+ * which subcommands accept the flag, where it is consumed, where it is
+ * forwarded, whether it is terminal (prints and exits) — so the next layer
+ * never silently drops the flag.
+ *
+ * @evidence contracts/common.md#principled-implementation The record separates token arity, command acceptance, consumer ownership, forwarding and terminal behavior because each controls a distinct parser or pipeline decision. Native capability discriminants prevent sending unsupported bare arguments to older hosts.
+ * @evidence contracts/common.md#clear-and-simple-design One schema row owns a flag's identities and routing policy, allowing parser, launcher classifications and generated native allow-lists to derive their views from the same declaration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Terminal and projectFree distinctions express real tool semantics, and internalShadow records user-visible ownership rather than matching fixture spellings or mutating the native parser.
+ * @evidence contracts/common.md#meaningful-documentation Members explain absence defaults, repeated-value ordering, terminal/project-free distinctions and capability ownership. Separate member paragraphs and blank lines follow the documentation skill's association and rationale guidance without property-level checklist tags.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export interface FlagSpec {
+  /**
+   * Canonical flag name including leading dashes (`"--singleThreaded"`). The
+   * generator normalizes canonical names and aliases to dash-free lowercase Go
+   * allow-list keys; the docs table retains this spelling in its first column.
+   */
+  readonly name: string;
+
+  /**
+   * Alternative spellings (`"-p"`, `"--project"` for `--tsconfig`). The parsing
+   * engine treats every alias as an equivalent of `name`.
+   */
+  readonly aliases?: readonly string[];
+
+  /** Argument shape: boolean / required value / optional value. */
+  readonly kind: FlagKind;
+
+  /**
+   * For `value` flags: optional validator. `positiveInt` mirrors the
+   * `--checkers minValue:1` constraint tsgo enforces.
+   */
+  readonly validator?: ValueValidator;
+
+  /** Subcommands that accept this flag. */
+  readonly subcommands: readonly AnySubcommand[];
+
+  /**
+   * Layers that read the flag into a typed option. Order matters only for
+   * documentation; the parsing engine merges across layers.
+   */
+  readonly consumedBy: readonly FlagLayer[];
+
+  /**
+   * Where the flag travels when the consuming layer does not absorb it. Default
+   * for any flag a layer does not consume is `"tsgo"` — i.e. the launcher
+   * forwards an unknown flag to tsgo via passthrough. Setting this to
+   * `undefined` while `consumedBy: ["launcher"]` is set means the flag is
+   * intentionally consumed-not-forwarded (e.g. ttsc-internal `--binary`).
+   */
+  readonly forwardTo?: FlagLayer;
+
+  /**
+   * Terminal flags ask the underlying tool to print something and exit
+   * (`--help`, `--version`, `--showConfig`, `--listFilesOnly`, `--all`,
+   * `--init`). ttsc must not wrap them in a pre-emit pass: the wrapped pass
+   * would run the printing command twice.
+   */
+  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` would fail 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
+   * user-visible behaviour (no double-print, no swallowed output). The shadow
+   * check is structural rather than `passthrough.includes("…")`.
+   *
+   * Currently true for `--listEmittedFiles`, `--noEmit`, `--pretty`.
+   */
+  readonly internalShadow?: boolean;
+
+  /**
+   * `true` when pinned tsgo only permits the option in tsconfig, except for
+   * command-line `false` or `null`. The launcher forwards the original argv so
+   * tsgo remains the diagnostic authority.
+   */
+  readonly tsconfigOnly?: boolean;
+
+  /**
+   * Native sidecar capability that must be declared before ttsc sends this flag
+   * as a bare optional compiler-control argument to a check-stage host. This
+   * does not describe the host's required subcommand/project/plugin protocol
+   * fields. Other forwarded compiler argv uses `TTSC_TSGO_ARGS`; launcher-owned
+   * options stay with their JavaScript consumer.
+   */
+  readonly nativeCapability?: "diagnosticsTiming" | "threadingArgs";
+
+  /** Human description for `--help` and the docs table. */
+  readonly description: string;
+}