ttsc 0.30.4 → 0.31.0

package/lib/flags/FLAG_SCHEMA.d.ts

@@ -0,0 +1,35 @@
+import type { FlagSpec } from "./FlagSpec";
+/**
+ * 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.
+ *
+ * One declaration per flag, consumed by every layer that needs to know about
+ * it:
+ *
+ * - `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.
+ *
+ * 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:
+ *
+ * 1. Every flag is uniquely identified by `name`; aliases must not collide with
+ *    other flags' `name` or `aliases`.
+ * 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. 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 declare const FLAG_SCHEMA: readonly FlagSpec[];

package/lib/flags/{schema.js → FLAG_SCHEMA.js}

@@ -1,34 +1,27 @@
 "use strict";
-// 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.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FLAG_BY_TOKEN = exports.FLAG_SCHEMA = void 0;
-exports.normalizeFlagToken = normalizeFlagToken;
-exports.resolveFlagSpec = resolveFlagSpec;
-exports.flagsForSubcommand = flagsForSubcommand;
-exports.buildGoAllowList = buildGoAllowList;
+exports.FLAG_SCHEMA = void 0;
 /**
- * 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.
+ * 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.
+ *
+ * One declaration per flag, consumed by every layer that needs to know about
+ * it:
+ *
+ * - `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.
+ *
+ * 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:
  *
@@ -37,9 +30,9 @@ exports.buildGoAllowList = buildGoAllowList;
  * 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.
  */
 exports.FLAG_SCHEMA = [
     // -------------------------------------------------------------------------
@@ -67,14 +60,16 @@ exports.FLAG_SCHEMA = [
     // 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",
@@ -138,7 +133,7 @@ exports.FLAG_SCHEMA = [
         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",
@@ -365,8 +360,8 @@ exports.FLAG_SCHEMA = [
     },
     // -------------------------------------------------------------------------
     // 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",
@@ -378,12 +373,10 @@ exports.FLAG_SCHEMA = [
         description: "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"],
@@ -465,16 +458,16 @@ exports.FLAG_SCHEMA = [
     },
     // -------------------------------------------------------------------------
     // `--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",
@@ -527,103 +520,4 @@ exports.FLAG_SCHEMA = [
         description: "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.
- */
-function normalizeFlagToken(token) {
-    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`.
- */
-function resolveFlagSpec(token) {
-    if (!token.startsWith("-"))
-        return undefined;
-    const equalsIndex = token.indexOf("=");
-    const name = equalsIndex === -1 ? token : token.slice(0, equalsIndex);
-    return exports.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.
- */
-exports.FLAG_BY_TOKEN = buildFlagIndex();
-function buildFlagIndex() {
-    const index = new Map();
-    for (const flag of exports.FLAG_SCHEMA) {
-        register(index, flag.name, flag);
-        for (const alias of flag.aliases ?? []) {
-            register(index, alias, flag);
-        }
-    }
-    return index;
-}
-function register(index, spelling, flag) {
-    // 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`. */
-function flagsForSubcommand(subcommand) {
-    return exports.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.
- */
-function buildGoAllowList(layer) {
-    const out = new Map();
-    for (const flag of exports.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;
-}
-//# sourceMappingURL=schema.js.map
+//# sourceMappingURL=FLAG_SCHEMA.js.map

package/lib/flags/FLAG_SCHEMA.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLAG_SCHEMA.js","sourceRoot":"","sources":["../../src/flags/FLAG_SCHEMA.ts"],"names":[],"mappings":"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"}

package/lib/flags/FlagKind.d.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/lib/flags/FlagKind.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FlagKind.js.map

package/lib/flags/FlagKind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlagKind.js","sourceRoot":"","sources":["../../src/flags/FlagKind.ts"],"names":[],"mappings":""}

package/lib/flags/FlagLayer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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" | "runBuild" | "tsgo" | "host" | "lint";

package/lib/flags/FlagLayer.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FlagLayer.js.map

package/lib/flags/FlagLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlagLayer.js","sourceRoot":"","sources":["../../src/flags/FlagLayer.ts"],"names":[],"mappings":""}

package/lib/flags/FlagSpec.d.ts

@@ -0,0 +1,104 @@
+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;
+}

package/lib/flags/FlagSpec.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FlagSpec.js.map

package/lib/flags/FlagSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlagSpec.js","sourceRoot":"","sources":["../../src/flags/FlagSpec.ts"],"names":[],"mappings":""}

package/lib/flags/ParseOptions.d.ts

@@ -0,0 +1,92 @@
+import type { AnySubcommand } from "./AnySubcommand";
+/**
+ * Options controlling a single `parseFlags` invocation.
+ *
+ * @evidence contracts/common.md#principled-implementation The record makes command identity and argument ownership explicit; separator and first-positional modes distinguish compiler argv from the runner program's argv without embedding caller branding or filesystem classification into the parser.
+ * @evidence contracts/common.md#clear-and-simple-design Parsing policy travels in one invocation record, with isPositional injecting only classification of tokens not already described by the flag schema or compiler table.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The caller-provided error prefix and positional predicate are explicit injection boundaries, not replacement of foreign parser behavior or project-specific special cases.
+ * @evidence contracts/common.md#meaningful-documentation Native comments describe mode interaction, predicate absence and compiler-arity precedence, with separated member explanations applying the documentation skill's optional-state and paragraph guidance.
+ * @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 ParseOptions {
+    /** Which subcommand's flag subset to accept. */
+    readonly subcommand: AnySubcommand;
+    /**
+     * Current parsing frame; callers remove an explicit leading command when
+     * present.
+     */
+    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;
+    /**
+     * Observe a validated launcher assignment at its compiler-frame position.
+     * The canonical schema name and parsed value retain alias/value semantics;
+     * passthroughIndex counts compiler tokens already forwarded at this point.
+     * Exceptions propagate from the caller's observer.
+     *
+     * @evidence contracts/common.md#principled-implementation Canonical validated assignments and their original forwarded-token positions let the launcher retain compiler-frame order without reparsing aliases or scalar operands.
+     * @evidence contracts/common.md#clear-and-simple-design One optional observer reports consumed assignments; parseFlags owns validation/consumption and the caller owns which metadata it retains.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts This declared callback conveys existing parser decisions rather than changing compiler parsing, adding a second grammar or inspecting caller-specific paths.
+     * @evidence contracts/common.md#meaningful-documentation Native prose defines canonical names, parsed values, frame coordinates and propagated observer errors; this is a function-valued contract rather than a data-property acknowledgment.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The callback signature specifies assignment metadata without choosing a filesystem or process operation; any native behavior belongs to its supplied implementation.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This signature chooses no observation algorithm; invocation frequency belongs to parseFlags and processing belongs to the supplied observer.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The signature coordinates no cross-invocation computation; retained metadata and reuse belong to its caller.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This function contract acquires no state or handles; the supplied callback and invoking parser own their lifetimes.
+     */
+    readonly onConsumedFlag?: (name: string, value: string | boolean | number, passthroughIndex: number) => void;
+    /**
+     * `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;
+    /**
+     * Enables `"--"` separator handling. Before the runner entry, following
+     * tokens go to compiler passthrough. Directly after the entry, one separator
+     * is consumed and following tokens go to the program tail; later program
+     * separators remain program arguments.
+     */
+    readonly honorDoubleDashSeparator?: boolean;
+    /**
+     * Classifies a bare (non-dash) token as a genuine positional argument (a
+     * source file, the ttsx entry, a project path) rather than the
+     * space-separated value of a preceding forwarded flag.
+     *
+     * When omitted, an unconsumed nonempty bare token in the active parser head
+     * is positional, except that runner first-positional mode still forwards
+     * unconsumed response-file tokens. Tokens after an honored separator or the
+     * runner entry belong to passthrough or the program tail without this
+     * policy.
+     *
+     * When provided, a bare token that fails the predicate is appended to
+     * `passthrough` in its original position instead of `positional`, so an
+     * unknown `--flag value` pair reaches tsgo with its adjacency and relative
+     * order intact. The native occurrence reader consumes compiler-owned operands
+     * before this predicate runs, using scalar, list and config-only metadata.
+     * Unconsumed lookahead remains a bare token, including whitespace the native
+     * list parser does not consume; empty tokens stay compiler passthrough and do
+     * not become launcher positionals.
+     *
+     * The main loop and schema-known non-native forwarding consult this policy
+     * only before program-tail forwarding and after native operand consumption.
+     * Empty-token and runner response-file handling remain separate parser
+     * rules.
+     *
+     * @evidence contracts/common.md#principled-implementation The predicate classifies only bare tokens whose arity is not already owned by the schema or compiler table, preserving their original position when they are forwarded values.
+     * @evidence contracts/common.md#clear-and-simple-design One optional callback exposes the caller's positional grammar while parseFlags owns token consumption and result partitioning.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts This documented injection point supplies caller policy without patching the compiler parser or guessing from fixture paths inside parseFlags.
+     * @evidence contracts/common.md#meaningful-documentation The comment explains absence, precedence and ordered forwarding, with separate paragraphs following the documentation skill; this is a function-valued contract, not a data-property acknowledgment.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This function-valued contract has no implementation or retained owner here; the supplied callback and invoking parser own their state and lifetimes.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This signature chooses no token-classification algorithm; parser invocation frequency and the supplied callback's text processing are reviewed at their respective implementations.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This signature coordinates no computation across consumers; any callback-owned shared work belongs to its implementation.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The callback signature defines a boolean token decision without specifying filesystem or process operations; any such behavior belongs to the supplied implementation, not an assumed pure body here.
+     */
+    readonly isPositional?: (token: string) => boolean;
+}

package/lib/flags/ParseOptions.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ParseOptions.js.map

package/lib/flags/ParseOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParseOptions.js","sourceRoot":"","sources":["../../src/flags/ParseOptions.ts"],"names":[],"mappings":""}