ttsc 0.12.4 → 0.13.1

package/lib/flags/parser.d.ts

@@ -0,0 +1,63 @@
+import type { AnySubcommand, ValueValidator } from "./schema";
+/**
+ * Per-subcommand parse result. `values` is keyed by the canonical flag
+ * name (e.g. `"--singleThreaded"`); boolean flags resolve to `true`/`false`,
+ * value flags to the parsed value type. Callers narrow with the helpers
+ * below (`getBoolean`, `getString`, `getNumber`).
+ */
+export interface ParseResult {
+    /** Canonical flag name → resolved value. */
+    readonly values: ReadonlyMap<string, string | boolean | number>;
+    /** Flags the engine did not consume — forwarded to tsgo. */
+    readonly passthrough: readonly string[];
+    /** Bare non-flag positional arguments, in original order. */
+    readonly positional: readonly string[];
+    /**
+     * Tokens that arrived after the `forwardAfterFirstPositional` sentinel.
+     * These are intended for the user's program (e.g. ttsx's entry-file argv);
+     * they are NOT forwarded to tsgo. Always empty when
+     * `forwardAfterFirstPositional` is false.
+     */
+    readonly tail: readonly string[];
+}
+/**
+ * Options controlling a single `parseFlags` invocation.
+ */
+export interface ParseOptions {
+    /** Which subcommand's flag subset to accept. */
+    readonly subcommand: AnySubcommand;
+    /** Argv tail (the launcher has already split off the subcommand). */
+    readonly argv: readonly string[];
+    /**
+     * Error prefix used when the parser throws (`"ttsc:"` or `"ttsx:"`). The
+     * engine itself is product-neutral; the caller controls the brand.
+     */
+    readonly errorPrefix: string;
+    /**
+     * `true` to treat the FIRST positional token as a sentinel that switches
+     * the engine to "forward everything after" mode (ttsx's entry-file
+     * behaviour: tokens after the entry are runtime argv, not tsgo flags).
+     * The sentinel itself is still recorded as a positional argument.
+     */
+    readonly forwardAfterFirstPositional?: boolean;
+    /**
+     * Optional `"--"` separator handling: when present in argv, every token
+     * after `--` is appended to `passthrough` as-is (ttsx already does this).
+     */
+    readonly honorDoubleDashSeparator?: boolean;
+}
+/**
+ * Parse `argv` according to FLAG_SCHEMA filtered by `subcommand`. Returns a
+ * `ParseResult`. Throws `Error` (with the configured prefix) on invalid
+ * input — unknown subcommand-only flag, missing required value, value that
+ * fails its validator.
+ */
+export declare function parseFlags(opts: ParseOptions): ParseResult;
+/** Return the boolean value of `flag` or `undefined` if not present. */
+export declare function getBoolean(result: ParseResult, flag: string): boolean | undefined;
+/** Return the string value of `flag` or `undefined` if not present. */
+export declare function getString(result: ParseResult, flag: string): string | undefined;
+/** Return the numeric value of `flag` or `undefined` if not present. */
+export declare function getNumber(result: ParseResult, flag: string): number | undefined;
+/** Marker type so docs callers can name the validator without an import dance. */
+export type { ValueValidator };

package/lib/flags/parser.js

@@ -0,0 +1,254 @@
+"use strict";
+// Schema-driven CLI parser used by both `runTtsc.ts` and `runTtsx.ts`.
+//
+// One engine, one schema. Each subcommand picks the subset of FLAG_SCHEMA it
+// accepts and feeds it through `parseFlags`. The engine returns:
+//
+//   * `values`      — typed values for every consumed flag.
+//   * `passthrough` — flags ttsc did not consume but must forward verbatim
+//                     to tsgo (or to native sidecars via `--tsgo-args`).
+//   * `positional`  — bare non-flag tokens (file paths, entry files, …).
+//
+// The schema is the spec; behaviour at every layer boundary is determined by
+// the FlagSpec attributes, not by ad-hoc `if (arg === "--foo")` branches.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFlags = parseFlags;
+exports.getBoolean = getBoolean;
+exports.getString = getString;
+exports.getNumber = getNumber;
+const schema_1 = require("./schema");
+/**
+ * Parse `argv` according to FLAG_SCHEMA filtered by `subcommand`. Returns a
+ * `ParseResult`. Throws `Error` (with the configured prefix) on invalid
+ * input — unknown subcommand-only flag, missing required value, value that
+ * fails its validator.
+ */
+function parseFlags(opts) {
+    const accepted = new Map();
+    for (const flag of (0, schema_1.flagsForSubcommand)(opts.subcommand)) {
+        // A flag enters the launcher's `accepted` set only when its
+        // `consumedBy` includes `"launcher"`. Flags consumed solely by tsgo
+        // or by native sidecars (e.g. `--showConfig`, `--listFilesOnly`)
+        // must fall through to `forwardKnownButUnaccepted` so the launcher
+        // forwards them verbatim instead of storing them in `values` where
+        // no consumer reads them back out. The previous shape — filter on
+        // `subcommands` only — silently dropped every tsgo-only terminal
+        // flag at the launcher boundary (the RC-1 / RC-2 class the schema
+        // is meant to make impossible).
+        if (!flag.consumedBy.includes("launcher"))
+            continue;
+        accepted.set(flag.name, flag);
+        for (const alias of flag.aliases ?? [])
+            accepted.set(alias, flag);
+    }
+    const values = new Map();
+    const passthrough = [];
+    const positional = [];
+    const tail = [];
+    let remainder = null;
+    if (opts.honorDoubleDashSeparator === true) {
+        const separator = opts.argv.indexOf("--");
+        if (separator !== -1) {
+            remainder = [...opts.argv.slice(separator + 1)];
+        }
+    }
+    const head = [
+        ...(remainder === null ? opts.argv : opts.argv.slice(0, indexOfSeparator(opts.argv))),
+    ];
+    let forwardingTail = false;
+    while (head.length !== 0) {
+        const current = head.shift();
+        if (forwardingTail) {
+            // Post-sentinel tokens belong to the user's program (e.g. the typia.ts
+            // entry's own argv: `ttsx typia.ts generate --input X`). They MUST NOT
+            // be forwarded to tsgo — the caller distinguishes `tail` from
+            // `passthrough` so script args never reach tsgo's option parser.
+            tail.push(current);
+            continue;
+        }
+        // `--foo=value` / `-p=value` form: split before resolving against the
+        // schema. Both long (`--foo`) and short (`-p`) aliases support the
+        // inline-value shape — without splitting the short form, `-p=value`
+        // would fall through as an unknown token and be forwarded to tsgo,
+        // bypassing the launcher's own consumer (e.g. plugin discovery against
+        // the wrong project root).
+        const equalsIndex = current.startsWith("-") ? current.indexOf("=") : -1;
+        const token = equalsIndex === -1 ? current : current.slice(0, equalsIndex);
+        const inlineValue = equalsIndex === -1 ? undefined : current.slice(equalsIndex + 1);
+        const flag = accepted.get(token);
+        if (flag !== undefined) {
+            consumeFlag(values, flag, token, inlineValue, head, opts.errorPrefix);
+            continue;
+        }
+        // Token IS a known flag but is not accepted by THIS subcommand. The
+        // engine forwards it to tsgo just like an unknown flag — the same
+        // policy the bare-lane parser applied (RC-1 prevention).
+        const globalFlag = schema_1.FLAG_BY_NAME.get(token);
+        if (globalFlag !== undefined) {
+            forwardKnownButUnaccepted(passthrough, globalFlag, current, inlineValue, head);
+            continue;
+        }
+        // Truly unknown `-`-prefixed token: forward to tsgo verbatim. This
+        // is what makes `ttsc --strict file.ts` work — ttsc does not need to
+        // re-implement every tsgo flag.
+        if (current.startsWith("-")) {
+            passthrough.push(current);
+            continue;
+        }
+        // Bare token: positional argument (file / entry / project path).
+        positional.push(current);
+        if (opts.forwardAfterFirstPositional === true &&
+            positional.length === 1) {
+            forwardingTail = true;
+        }
+    }
+    if (remainder !== null) {
+        // `--` separator: everything after goes to the user program when we are
+        // in tail mode (ttsx after the entry), otherwise to tsgo as passthrough.
+        const sink = forwardingTail ? tail : passthrough;
+        for (const token of remainder)
+            sink.push(token);
+    }
+    return { values, passthrough, positional, tail };
+}
+/**
+ * Pull the value for `flag` from either `inlineValue` (`--flag=value`) or
+ * the next argv token (`--flag value`), validate it per the schema, and
+ * write it to the result map.
+ */
+function consumeFlag(values, flag, token, inlineValue, rest, errorPrefix) {
+    if (flag.kind === "boolean") {
+        if (inlineValue !== undefined) {
+            // `--flag=false` / `--flag=true` inline form. Anything other than
+            // a recognised literal stays loud: `--singleThreaded=yes` silently
+            // becoming `true` is the kind of footgun the RCA's RC-4 class
+            // covers. Mirrors `validatePositiveInt`'s style.
+            const literal = parseBooleanLiteral(inlineValue);
+            if (literal === undefined) {
+                throw new Error(`${errorPrefix} ${token} expects \`true\` or \`false\`, got ${JSON.stringify(inlineValue)}`);
+            }
+            values.set(flag.name, literal);
+            return;
+        }
+        // Space form `--flag true` / `--flag false`: peek the next token and
+        // consume it only when it parses as a boolean literal. tsgo accepts
+        // this shape natively; the launcher must mirror it so `ttsc --noEmit
+        // false` does not corrupt argv (positional sink getting `false`,
+        // tsgo seeing it as a stray input file).
+        if (rest.length > 0) {
+            const peek = parseBooleanLiteral(rest[0]);
+            if (peek !== undefined) {
+                rest.shift();
+                values.set(flag.name, peek);
+                return;
+            }
+        }
+        values.set(flag.name, true);
+        return;
+    }
+    const raw = inlineValue !== undefined ? inlineValue : takeValueToken(token, rest, errorPrefix);
+    if (flag.validator === "positiveInt") {
+        values.set(flag.name, validatePositiveInt(token, raw, errorPrefix));
+        return;
+    }
+    values.set(flag.name, raw);
+}
+/**
+ * Read the value token that follows `flag`. Throws if argv ends here OR if
+ * the next token looks like another flag (`-` prefix). Without the
+ * "looks like a flag" guard `ttsc --cwd --strict src/main.ts` would silently
+ * consume `--strict` as the value of `--cwd`, leaving `--strict` lost and
+ * `cwd` set to a junk path. Mirrors the symmetric guard already in
+ * `forwardKnownButUnaccepted` (RC-1 fairness — the two value-resolution
+ * paths must agree on what counts as "a missing value").
+ */
+function takeValueToken(flag, rest, errorPrefix) {
+    const value = rest.shift();
+    if (value === undefined) {
+        throw new Error(`${errorPrefix} ${flag} requires a value`);
+    }
+    if (value.startsWith("-")) {
+        // Put it back so the next loop iteration parses it as its own flag.
+        rest.unshift(value);
+        throw new Error(`${errorPrefix} ${flag} requires a value (next token ${JSON.stringify(value)} starts with "-")`);
+    }
+    return value;
+}
+/**
+ * Parse a CLI boolean literal — `true`/`false` only (case-sensitive to
+ * match tsgo's parser). Returns `undefined` for any other token so the
+ * caller knows to throw or treat as a non-value.
+ */
+function parseBooleanLiteral(raw) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    return undefined;
+}
+/**
+ * Validate a `positiveInt` value. Mirrors tsgo's `--checkers minValue:1`
+ * constraint so a typo fails loudly at the launcher rather than reaching
+ * tsgo with an invalid argument.
+ */
+function validatePositiveInt(flag, raw, errorPrefix) {
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${errorPrefix} ${flag} expects a positive integer, got ${JSON.stringify(raw)}`);
+    }
+    return value;
+}
+/**
+ * Forward a flag the schema knows about but the current subcommand does
+ * not accept. The launcher will hand it to tsgo (or to native sidecars
+ * via `--tsgo-args`); without this branch the parser would lose the
+ * value token of a `--flag value` pair.
+ */
+function forwardKnownButUnaccepted(passthrough, flag, original, inlineValue, rest) {
+    passthrough.push(original);
+    // Boolean flags carry no value. `--foo=value` already encodes the value
+    // inline. Otherwise the next argv token is the flag's value: keep it
+    // adjacent so tsgo receives the pair intact.
+    if (flag.kind === "boolean" || inlineValue !== undefined) {
+        return;
+    }
+    if (rest.length === 0)
+        return;
+    if (rest[0].startsWith("-"))
+        return;
+    passthrough.push(rest.shift());
+}
+/**
+ * Return the index of the `--` separator in `argv`, or `argv.length` when
+ * absent. The parser slices on this index when honorDoubleDashSeparator.
+ */
+function indexOfSeparator(argv) {
+    const index = argv.indexOf("--");
+    return index === -1 ? argv.length : index;
+}
+// -----------------------------------------------------------------------------
+// Typed accessors. The parser stores raw values (string | boolean | number) so
+// the engine stays untyped; callers pick the shape per flag.
+// -----------------------------------------------------------------------------
+/** Return the boolean value of `flag` or `undefined` if not present. */
+function getBoolean(result, flag) {
+    const value = result.values.get(flag);
+    if (typeof value === "boolean")
+        return value;
+    return undefined;
+}
+/** Return the string value of `flag` or `undefined` if not present. */
+function getString(result, flag) {
+    const value = result.values.get(flag);
+    if (typeof value === "string")
+        return value;
+    return undefined;
+}
+/** Return the numeric value of `flag` or `undefined` if not present. */
+function getNumber(result, flag) {
+    const value = result.values.get(flag);
+    if (typeof value === "number")
+        return value;
+    return undefined;
+}
+//# sourceMappingURL=parser.js.map

package/lib/flags/parser.js.map

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

package/lib/flags/schema.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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" | "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:
+ *
+ * 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).
+ */
+export type FlagLayer = "launcher" | "runBuild" | "tsgo" | "host" | "lint";
+/**
+ * Argument shape of a flag.
+ *
+ * - `boolean` — `--flag` / `--flag=true` / `--flag=false`. No value token is
+ *   consumed.
+ * - `value` — `--flag value` or `--flag=value`. Required 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 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;
+    /**
+     * 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.
+ *
+ * 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. 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.
+ */
+export declare const FLAG_SCHEMA: readonly FlagSpec[];
+/**
+ * Lookup of `name` and every alias → its canonical FlagSpec. Built once at
+ * module load so the parsing engine has O(1) flag resolution.
+ */
+export declare const FLAG_BY_NAME: ReadonlyMap<string, FlagSpec>;
+/**
+ * Terminal flags as a derived set. Used by `runBuild.ts` to skip the pre-emit
+ * pass when one is present.
+ */
+export declare const TERMINAL_FLAGS: ReadonlySet<string>;
+/**
+ * `internalShadow: true` flags as a derived set. Used by `runBuild.ts` to
+ * detect a user-forwarded copy of a flag ttsc adds internally so the
+ * post-processor does not eat the user's output.
+ */
+export declare const INTERNAL_SHADOW_FLAGS: ReadonlySet<string>;
+/** Tokens (canonical name + aliases) accepted in `subcommand`. */
+export declare function flagsForSubcommand(subcommand: AnySubcommand): FlagSpec[];
+/**
+ * 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 declare function buildGoAllowList(layer: "host" | "lint"): Map<string, boolean>;