ttsc 0.30.3 → 0.31.0

package/lib/flags/parseFlags.d.ts

@@ -0,0 +1,18 @@
+import type { ParseOptions } from "./ParseOptions";
+import type { ParseResult } from "./ParseResult";
+/**
+ * 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 declare function parseFlags(opts: ParseOptions): ParseResult;

package/lib/flags/parseFlags.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFlags = parseFlags;
+const flagsForSubcommand_1 = require("./flagsForSubcommand");
+const normalizeFlagToken_1 = require("./normalizeFlagToken");
+const readCompilerOptionOccurrence_1 = require("./readCompilerOptionOccurrence");
+const resolveFlagSpec_1 = require("./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.
+ */
+function parseFlags(opts) {
+    const accepted = launcherFlagsForSubcommand(opts.subcommand);
+    const values = new Map();
+    const repeated = new Map();
+    const passthrough = [];
+    const positional = [];
+    const tail = [];
+    // 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 = separator === -1 ? null : opts.argv.slice(separator + 1);
+    const head = {
+        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((0, normalizeFlagToken_1.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 = (0, resolveFlagSpec_1.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 ((0, readCompilerOptionOccurrence_1.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 };
+}
+const launcherFlagsBySubcommand = new Map();
+/** Reuse the immutable schema's launcher acceptance index for one command. */
+function launcherFlagsForSubcommand(subcommand) {
+    const cached = launcherFlagsBySubcommand.get(subcommand);
+    if (cached !== undefined)
+        return cached;
+    const accepted = new Map();
+    for (const flag of (0, flagsForSubcommand_1.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((0, normalizeFlagToken_1.normalizeFlagToken)(flag.name), flag);
+        for (const alias of flag.aliases ?? []) {
+            accepted.set((0, normalizeFlagToken_1.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, repeated, flag, token, inlineValue, rest, errorPrefix) {
+    const record = (value) => {
+        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, rest, errorPrefix) {
+    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) {
+    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, raw, errorPrefix) {
+    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, flag, original, inlineValue, rest, isPositional) {
+    passthrough.push(original);
+    const native = (0, readCompilerOptionOccurrence_1.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++]);
+}
+//# sourceMappingURL=parseFlags.js.map

package/lib/flags/parseFlags.js.map

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

package/lib/flags/readCompilerOptionOccurrence.d.ts

@@ -0,0 +1,34 @@
+import type { CompilerOptionSpec } from "./CompilerOptionSpec";
+/**
+ * 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 declare function readCompilerOptionOccurrence(argv: readonly string[], index: number): CompilerOptionOccurrence;
+/**
+ * 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;
+}
+export {};

package/lib/flags/readCompilerOptionOccurrence.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCompilerOptionOccurrence = readCompilerOptionOccurrence;
+const COMPILER_ENUM_WHITESPACE_1 = require("./COMPILER_ENUM_WHITESPACE");
+const COMPILER_OPTIONS_1 = require("./COMPILER_OPTIONS");
+const normalizeFlagToken_1 = require("./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.
+ */
+function readCompilerOptionOccurrence(argv, index) {
+    const token = argv[index];
+    const option = token?.startsWith("-") === true && !token.includes("=")
+        ? COMPILER_OPTIONS_1.COMPILER_OPTIONS.get((0, normalizeFlagToken_1.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_1.COMPILER_ENUM_WHITESPACE.has(character)));
+        return { option, width: empty ? 1 : 2, needsFence: next.startsWith("-") };
+    }
+    return { option, width: 2, needsFence: false };
+}
+//# sourceMappingURL=readCompilerOptionOccurrence.js.map

package/lib/flags/readCompilerOptionOccurrence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readCompilerOptionOccurrence.js","sourceRoot":"","sources":["../../src/flags/readCompilerOptionOccurrence.ts"],"names":[],"mappings":";;;AAAA,yEAAsE;AACtE,yDAAsD;AAEtD,6DAA0D;AAE1D;;;;;;;;;;;;;;GAcG;AACH,sCACE,IAAuB,EACvB,KAAa;IAEb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,MAAM,GACV,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACrD,CAAC,CAAC,mCAAgB,CAAC,GAAG,CAAC,IAAA,uCAAkB,EAAC,KAAK,CAAC,CAAC;QACjD,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACjE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,SAAS;QACpB,OAAO;YACL,MAAM;YACN,KAAK,EAAE,CAAC;YACR,UAAU,EAAE,KAAK;YACjB,YAAY,EACV,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;SACrE,CAAC;IACJ,IAAI,IAAI,KAAK,MAAM;QACjB,OAAO;YACL,MAAM;YACN,KAAK,EAAE,CAAC;YACR,UAAU,EAAE,KAAK;YACjB,YAAY,EAAE,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;SAC5D,CAAC;IACJ,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAC3B,OAAO;YACL,MAAM;YACN,KAAK,EAAE,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAClD,YAAY,EACV,MAAM,CAAC,UAAU,IAAI,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO;YACtE,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;SACjC,CAAC;IACJ,IAAI,MAAM,CAAC,UAAU;QACnB,OAAO;YACL,MAAM;YACN,KAAK,EAAE,IAAI,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnD,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;SACjC,CAAC;IACJ,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,wEAAwE;QACxE,uEAAuE;QACvE,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,MAAM,UAAU,GAAG,kBAAkB,CAAC;QACtC,OAAO,KAAK,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAE,CAAC;YAAE,KAAK,EAAE,CAAC;QAC7D,OAAO,GAAG,GAAG,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAE,CAAC;YAAE,GAAG,EAAE,CAAC;QAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACvC,qEAAqE;QACrE,mEAAmE;QACnE,MAAM,KAAK,GACT,OAAO,KAAK,EAAE;YACd,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YACvB,OAAO;iBACJ,KAAK,CAAC,GAAG,CAAC;iBACV,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CACd,MAAM,CAAC,OAAO,KAAK,QAAQ;gBACzB,CAAC,CAAC,IAAI,KAAK,EAAE;gBACb,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,CAC5B,mDAAwB,CAAC,GAAG,CAAC,SAAS,CAAC,CACxC,CACN,CAAC;QACN,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;IAC5E,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC"}

package/lib/flags/readCompilerOptionValues.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare function readCompilerOptionValues(argv?: readonly string[]): CompilerOptionValues;
+/** 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[];
+}
+export {};

package/lib/flags/readCompilerOptionValues.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCompilerOptionValues = readCompilerOptionValues;
+const normalizeCompilerEnumValue_1 = require("./normalizeCompilerEnumValue");
+const readCompilerOptionOccurrence_1 = require("./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.
+ */
+function readCompilerOptionValues(argv = []) {
+    const values = new Map();
+    const responseFiles = [];
+    for (let index = 0; index < argv.length;) {
+        const occurrence = (0, readCompilerOptionOccurrence_1.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"
+                        ? (0, normalizeCompilerEnumValue_1.normalizeCompilerEnumValue)(next, "cli")
+                        : next);
+                }
+            }
+        }
+        index += occurrence.width;
+    }
+    return { values, responseFiles };
+}
+//# sourceMappingURL=readCompilerOptionValues.js.map

package/lib/flags/readCompilerOptionValues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readCompilerOptionValues.js","sourceRoot":"","sources":["../../src/flags/readCompilerOptionValues.ts"],"names":[],"mappings":";;;AAAA,6EAA0E;AAC1E,iFAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kCACE,IAAI,GAAsB,EAAE;IAE5B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC1C,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,GAAI,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAA,2DAA4B,EAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7B,IAAI,IAAI,CAAC,KAAK,CAAE,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAE,CAAC,CAAC;QACnE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,IAAI,KAAK,MAAM;gBAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;iBAC9C,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACnC,IAAI,UAAU,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;oBAC1C,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;gBACnD,CAAC;YACH,CAAC;iBAAM,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;gBAC9B,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;oBAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;qBAC3D,IAAI,UAAU,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;oBAChC,MAAM,CAAC,GAAG,CACR,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,IAAI,KAAK,MAAM;wBACpB,CAAC,CAAC,IAAA,uDAA0B,EAAC,IAAK,EAAE,KAAK,CAAC;wBAC1C,CAAC,CAAC,IAAI,CACT,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QACD,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAC5B,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AACnC,CAAC"}

package/lib/flags/resolveFlagSpec.d.ts

@@ -0,0 +1,21 @@
+import type { FlagSpec } from "./FlagSpec";
+/**
+ * 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 declare function resolveFlagSpec(token: string): FlagSpec | undefined;

package/lib/flags/resolveFlagSpec.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFlagSpec = resolveFlagSpec;
+const FLAG_BY_TOKEN_1 = require("./FLAG_BY_TOKEN");
+const normalizeFlagToken_1 = require("./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.
+ */
+function resolveFlagSpec(token) {
+    if (!token.startsWith("-"))
+        return undefined;
+    const equalsIndex = token.indexOf("=");
+    const name = equalsIndex === -1 ? token : token.slice(0, equalsIndex);
+    return FLAG_BY_TOKEN_1.FLAG_BY_TOKEN.get((0, normalizeFlagToken_1.normalizeFlagToken)(name));
+}
+//# sourceMappingURL=resolveFlagSpec.js.map

package/lib/flags/resolveFlagSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveFlagSpec.js","sourceRoot":"","sources":["../../src/flags/resolveFlagSpec.ts"],"names":[],"mappings":";;;AAAA,mDAAgD;AAEhD,6DAA0D;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,yBAAgC,KAAa;IAC3C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACtE,OAAO,6BAAa,CAAC,GAAG,CAAC,IAAA,uCAAkB,EAAC,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC"}