ttsc 0.30.3 → 0.31.0

package/lib/compiler/internal/build/CompilerDiagnostics.js

@@ -0,0 +1,270 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompilerDiagnostics = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Reading and comparing the compiler diagnostics a build printed.
+ *
+ * Ttsc receives diagnostics as rendered text from two producers, TypeScript-Go
+ * and native plugin hosts, and has to turn that text into structured
+ * {@link ITtscCompilerDiagnostic} values and decide when two reports are the
+ * same problem. The comparison is what lets a failed plugin run fall back to a
+ * plain type-check without printing each TypeScript error twice.
+ *
+ * @evidence contracts/common.md#principled-implementation Rendered-format parsing and typed diagnostic identity are grouped without conflating report suppression with successful build status.
+ * @evidence contracts/common.md#clear-and-simple-design Public parsing, terminal-text cleaning and fallback selection share private normalizers/indexing rather than duplicating compiler report semantics across build lanes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The API compares actual producer reports and preserves plugin codes instead of treating selected error strings as authoritative expected answers.
+ * @evidence contracts/common.md#meaningful-documentation Namespace prose explains both producer formats and the failed-plugin fallback purpose; selected functions state coordinates, identity rules and null outcomes.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This namespace grouping owns no native operation; selected parsing and filtering functions acknowledge their filename boundary separately.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Processing choices belong to the selected parser/filter functions, not this namespace representation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The grouping retains no diagnostic index across invocations; each selection operation owns its applicable reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No resource or historical diagnostic store is acquired by the namespace.
+ */
+var CompilerDiagnostics;
+(function (CompilerDiagnostics) {
+    /**
+     * Return fallback diagnostics the failed plugin did not already report.
+     * Matching offsets take precedence only when both reports carry offsets;
+     * otherwise rendered line and column determine the position. A completely
+     * redundant fallback returns null. Partial filtering retains selected report
+     * context, drops summary lines, and rejoins text with LF separators; text
+     * before the first recognized report and nonindented context also survives.
+     *
+     * @evidence contracts/common.md#principled-implementation Identity includes category, typed code, file and headline; separate offset and rendered-position indexes preserve the pairwise rule when an offset is missing.
+     * @evidence contracts/common.md#clear-and-simple-design Structured selection precedes rendered-text filtering, keeping diagnostic identity in one index helper and continuation handling in one text helper.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Fallback suppression compares actual reports and preserves surviving output; it does not recognize fixed error codes or suppress a failing status to satisfy an example.
+     * @evidence contracts/common.md#meaningful-documentation The native comment explains position precedence, the null result and text-context preservation with prose separated from tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Rendered relative filenames are resolved by node:path against the compiler cwd; report filenames otherwise retain the producer's native spelling without guessed case folding.
+     * @evidence contracts/performance.md#efficient-algorithms Separate identity/offset/position indexes avoid failure-by-fallback and selected-by-line cross products. Building and querying keys includes headline scans, JSON tuple serialization and hashing of diagnostic text; partial stdout/stderr filtering performs ANSI removal, format regex matching and native path normalization per line. Work and temporary records depend on diagnostic, line and text sizes; regex backtracking is not bounded by index cardinality.
+     * @evidence contracts/performance.md#reuse-equivalent-work The selected diagnostic index is shared by stdout and stderr filtering, since both outputs refer to the same surviving population.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Diagnostic indexes and output arrays are invocation-local; this function owns no persistent cache or handle.
+     */
+    function filterReportedTypeScriptDiagnostics(failure, typechecked, cwd) {
+        if (typechecked.diagnostics.length === 0) {
+            return typechecked.status === 0 ? null : typechecked;
+        }
+        const alreadyReported = indexCompilerDiagnostics(failure.diagnostics);
+        const diagnostics = typechecked.diagnostics.filter((diagnostic) => !alreadyReported(diagnostic));
+        if (diagnostics.length === 0)
+            return null;
+        if (diagnostics.length === typechecked.diagnostics.length)
+            return typechecked;
+        const selected = indexCompilerDiagnostics(diagnostics);
+        return {
+            ...typechecked,
+            diagnostics,
+            stderr: filterCompilerDiagnosticText(typechecked.stderr, selected, cwd),
+            stdout: filterCompilerDiagnosticText(typechecked.stdout, selected, cwd),
+        };
+    }
+    CompilerDiagnostics.filterReportedTypeScriptDiagnostics = filterReportedTypeScriptDiagnostics;
+    /** Remove diagnostic lines absent from the selected structured result. */
+    function filterCompilerDiagnosticText(text, selected, cwd) {
+        const out = [];
+        let keepContinuation = true;
+        for (const line of text.split(/\r?\n/)) {
+            const plain = stripAnsi(line);
+            const diagnostic = parseDiagnosticLine(plain, cwd);
+            if (diagnostic !== null) {
+                keepContinuation = selected(diagnostic);
+                if (keepContinuation)
+                    out.push(line);
+                continue;
+            }
+            if (/^Found\s+\d+\s+errors?/i.test(plain))
+                continue;
+            if (!keepContinuation && /^\s+/.test(line))
+                continue;
+            keepContinuation = true;
+            out.push(line);
+        }
+        return out.join("\n");
+    }
+    /**
+     * Index pairwise diagnostic matches without treating them as an equivalence
+     * relation: an offset-bearing report can match an offset-free report by
+     * rendered position, even when two offset-bearing reports do not match.
+     * Separate fallback positions preserve that distinction. NaN never equals
+     * itself under the original strict numeric comparison.
+     */
+    function indexCompilerDiagnostics(diagnostics) {
+        const indexed = new Map();
+        for (const diagnostic of diagnostics) {
+            const identity = diagnosticIdentity(diagnostic);
+            if (identity === undefined)
+                continue;
+            let positions = indexed.get(identity);
+            if (positions === undefined) {
+                positions = {
+                    starts: new Set(),
+                    positions: new Set(),
+                    fallbackPositions: new Set(),
+                };
+                indexed.set(identity, positions);
+            }
+            const rendered = diagnosticRenderedPosition(diagnostic);
+            if (rendered !== undefined) {
+                positions.positions.add(rendered);
+                if (diagnostic.start === undefined)
+                    positions.fallbackPositions.add(rendered);
+            }
+            if (diagnostic.start !== undefined && !Number.isNaN(diagnostic.start))
+                positions.starts.add(diagnostic.start);
+        }
+        return (diagnostic) => {
+            const identity = diagnosticIdentity(diagnostic);
+            if (identity === undefined)
+                return false;
+            const positions = indexed.get(identity);
+            if (positions === undefined)
+                return false;
+            const rendered = diagnosticRenderedPosition(diagnostic);
+            if (diagnostic.start === undefined)
+                return rendered !== undefined && positions.positions.has(rendered);
+            return ((!Number.isNaN(diagnostic.start) &&
+                positions.starts.has(diagnostic.start)) ||
+                (rendered !== undefined && positions.fallbackPositions.has(rendered)));
+        };
+    }
+    /** Preserve numeric versus plugin-string codes in an unambiguous tuple. */
+    function diagnosticIdentity(diagnostic) {
+        if (typeof diagnostic.code === "number" && Number.isNaN(diagnostic.code))
+            return undefined;
+        return JSON.stringify([
+            diagnostic.category,
+            typeof diagnostic.code,
+            String(diagnostic.code),
+            diagnostic.file,
+            diagnosticHeadline(diagnostic.messageText),
+        ]);
+    }
+    /** Missing positions match missing positions, but NaN coordinates never do. */
+    function diagnosticRenderedPosition(diagnostic) {
+        if (Number.isNaN(diagnostic.line) || Number.isNaN(diagnostic.character))
+            return undefined;
+        return JSON.stringify([
+            diagnostic.line === undefined ? null : String(diagnostic.line),
+            diagnostic.character === undefined ? null : String(diagnostic.character),
+        ]);
+    }
+    /** Remove pretty-rendered source context from a diagnostic message. */
+    function diagnosticHeadline(message) {
+        return message.split(/\r?\n/, 1)[0].trim();
+    }
+    /**
+     * Try to parse a single line as a TypeScript compiler diagnostic in one of
+     * three formats:
+     *
+     * - `file:line:col - category TSxxxx: message` (colon-separated, tsgo style)
+     * - `file(line,col): category TSxxxx: message` (paren style, classic tsc)
+     * - `category TSxxxx: message` (global, no file)
+     *
+     * Codes may also be bare digits or plugin-defined tokens. Line and column
+     * retain the producer's one-based coordinates. Relative filenames remain
+     * relative when cwd is absent. Returns null for an unrecognized line.
+     *
+     * @evidence contracts/common.md#principled-implementation Anchored format recognizers distinguish file and global reports; only TS-prefixed or bare numeric codes become numbers, preserving plugin-code identity.
+     * @evidence contracts/common.md#clear-and-simple-design Three explicit render formats feed the same category, code and filename normalizers; unrecognized text is left for the caller's continuation handling.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Patterns implement compiler and plugin render formats instead of matching selected messages or coercing arbitrary plugin prefixes into TypeScript numbers.
+     * @evidence contracts/common.md#meaningful-documentation Native documentation gives accepted forms, coordinate units, optional cwd meaning and the null outcome in separated paragraphs.
+     * @evidence contracts/portability.md#os-neutral-implementation Native node:path recognizes absolute paths and resolves relative paths against cwd; greedy filename captures retain drive colons without treating protocol spelling as filesystem identity.
+     * @evidence contracts/performance.md#efficient-algorithms At most three anchored format matches precede category/code conversion and native filename normalization. Captures, numeric token conversion and path text contribute processing/storage cost; the greedy/optional filename patterns can backtrack on malformed lines, so three recognizers do not establish a linear-time ceiling.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This parser coordinates no repeated producer or cross-request computation; diagnostic indexing belongs to the selecting operation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A parsed record is returned immediately; the parser retains no history or native resource.
+     */
+    function parseDiagnosticLine(line, cwd) {
+        const colonMatch = line.match(/^(.+):(\d+):(\d+)\s+-\s+(error|warning|suggestion|message)\s+(\d+|[A-Z][A-Z0-9_-]*):\s+(.+)$/i);
+        if (colonMatch) {
+            return {
+                category: normalizeDiagnosticCategory(colonMatch[4]),
+                character: Number(colonMatch[3]),
+                code: normalizeDiagnosticCode(colonMatch[5]),
+                file: normalizeDiagnosticFile(colonMatch[1], cwd),
+                line: Number(colonMatch[2]),
+                messageText: colonMatch[6],
+            };
+        }
+        const fileMatch = line.match(/^(.+?)\((\d+),(\d+)\):\s+(error|warning|suggestion|message)\s+(\d+|[A-Z][A-Z0-9_-]*):\s+(.+)$/i);
+        if (fileMatch) {
+            return {
+                category: normalizeDiagnosticCategory(fileMatch[4]),
+                character: Number(fileMatch[3]),
+                code: normalizeDiagnosticCode(fileMatch[5]),
+                file: normalizeDiagnosticFile(fileMatch[1], cwd),
+                line: Number(fileMatch[2]),
+                messageText: fileMatch[6],
+            };
+        }
+        const globalMatch = line.match(/^(error|warning|suggestion|message)\s+(\d+|[A-Z][A-Z0-9_-]*):\s+(.+)$/i);
+        if (!globalMatch) {
+            return null;
+        }
+        return {
+            category: normalizeDiagnosticCategory(globalMatch[1]),
+            code: normalizeDiagnosticCode(globalMatch[2]),
+            file: null,
+            messageText: globalMatch[3],
+        };
+    }
+    CompilerDiagnostics.parseDiagnosticLine = parseDiagnosticLine;
+    /**
+     * Preserve absolute filenames and resolve relative filenames against cwd when
+     * supplied; an absent cwd preserves the relative producer spelling.
+     */
+    function normalizeDiagnosticFile(file, cwd) {
+        if (node_path_1.default.isAbsolute(file) || cwd === undefined) {
+            return file;
+        }
+        return node_path_1.default.resolve(cwd, file);
+    }
+    /**
+     * Map a raw category string (`"error"`, `"warning"`, `"suggestion"`,
+     * `"message"`) to the canonical `ITtscCompilerDiagnostic.Category`. Any
+     * unrecognised value is coerced to `"error"`.
+     */
+    function normalizeDiagnosticCategory(value) {
+        const lowered = value.toLowerCase();
+        return lowered === "warning" ||
+            lowered === "suggestion" ||
+            lowered === "message"
+            ? lowered
+            : "error";
+    }
+    /**
+     * Parse a diagnostic code as a number when it is TypeScript's own spelling
+     * (`TS2322`, or bare digits), or keep the whole token as a string for a
+     * plugin-defined code. Only the `TS` prefix is TypeScript's; stripping any
+     * other letters would turn a plugin's `FOO123` into TypeScript's `123`.
+     */
+    function normalizeDiagnosticCode(value) {
+        const numeric = /^(?:TS)?(\d+)$/i.exec(value);
+        return numeric === null ? value : Number(numeric[1]);
+    }
+    /**
+     * Strip ANSI escape sequences from `text` for line-by-line diagnostic
+     * parsing.
+     *
+     * @evidence contracts/common.md#principled-implementation The CSI pattern removes terminal control sequences while retaining diagnostic text for format parsing.
+     * @evidence contracts/common.md#clear-and-simple-design One text transformation serves both structured parsing and selected-output filtering without coupling either caller's state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts This strips recognized control syntax, not error messages or producer-specific expected outputs.
+     * @evidence contracts/common.md#meaningful-documentation The native comment states the parsing purpose and supported escape family; descriptive prose precedes the acknowledgment block.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This function transforms terminal text without accessing native paths, filesystem capabilities or processes.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms One global scan constructs the stripped text in space proportional to the input; no per-character array or repeated prefix concatenation is used.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Stripping one supplied string does not coordinate a shared producer or retained cross-request result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The string transformation owns no retained cache or handle.
+     */
+    function stripAnsi(text) {
+        return text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
+    }
+    CompilerDiagnostics.stripAnsi = stripAnsi;
+})(CompilerDiagnostics || (exports.CompilerDiagnostics = CompilerDiagnostics = {}));
+//# sourceMappingURL=CompilerDiagnostics.js.map

package/lib/compiler/internal/build/CompilerDiagnostics.js.map

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

package/lib/compiler/internal/build/NativePluginArguments.d.ts

@@ -0,0 +1,114 @@
+import type { ITtscLoadedNativePlugin } from "../../../structures/internal/ITtscLoadedNativePlugin";
+import type { TtscBuildOptions } from "../../../structures/internal/TtscBuildOptions";
+import type { BuildExecution } from "./BuildExecution";
+import type { RunBuildOptions } from "./RunBuildOptions";
+/**
+ * The argv ttsc hands to a native plugin host.
+ *
+ * A native host speaks its own subcommands (`build`, `check`, `fix`, `format`,
+ * `project-inputs`) and receives the project, the plugin list, and the compiler
+ * flags as separate arguments rather than one tsgo command line. Optional
+ * capabilities a host declares (threading, diagnostics timing) decide which of
+ * ttsc's optional arguments are sent. This negotiation avoids sending those
+ * extensions to undeclared hosts; it does not certify every host's acceptance
+ * of the core protocol or the truth of its capability declaration.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace separates the host subcommand protocol from compiler forwarding and uses declared capabilities for optional host fields.
+ * @evidence contracts/common.md#clear-and-simple-design Build, check and input-query composers share descriptor serialization while preserving each command's own supported modifiers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional protocol extensions require capabilities instead of mutating foreign flag sets or dispatching on a particular plugin name.
+ * @evidence contracts/common.md#meaningful-documentation Namespace prose states protocol separation and capability purpose; composer comments explain project context, command effects and payload fields.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The grouping itself defines no native path representation; its selected argv composers address the paths they carry.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace contains no processing strategy apart from its separately selected composers and serializer.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This API grouping retains no completed or in-flight host query or payload.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No native host, buffer history or handle is owned by the namespace.
+ */
+export declare namespace NativePluginArguments {
+    /**
+     * Compose a shared transform host's build or no-emit check command.
+     * Project-context arguments require the selected host's capability; quiet
+     * modifiers remain absent on the compatibility check lane.
+     *
+     * A supplied provenancePath is a private absolute artifact destination and
+     * requires explicit emitProvenance support from the selected host.
+     *
+     * @evidence contracts/common.md#principled-implementation Emit selection chooses build versus check; the selected host's independent capabilities gate explicit project context and a supplied absolute emit-proof artifact destination.
+     * @evidence contracts/common.md#clear-and-simple-design Core protocol argv precedes optional project/output/verbosity fields; compiler passthrough travels separately through the environment.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Capability checks and omission of build-only modifiers protect actual strict-host protocol differences without recognizing plugin names or altering foreign flag parsers.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain shared-host selection, no-emit compatibility modifiers and the optional private provenance path's capability/absolute-path premise.
+     * @evidence contracts/portability.md#os-neutral-implementation Native output paths resolve against execution cwd and remain individual argv elements; JSON serialization preserves plugin payload without shell escaping.
+     * @evidence contracts/performance.md#efficient-algorithms Plugin projection/JSON encoding follows plugin count, name/stage text and configuration serialization work. Selected-host capability lookups may each scan the plugin list; optional project-context serialization and native output-path resolution add payload/path-text costs. Returned argv storage follows composed bytes.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure argv composition coordinates no shared producer or retained cross-request result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Arguments are returned to the process owner and no process or persistent buffer is acquired here.
+     */
+    function createNativeBuildArgs(execution: ReturnType<typeof BuildExecution.resolveExecutionContext>, options: RunBuildOptions, plugins: readonly ITtscLoadedNativePlugin[], provenancePath?: string): string[];
+    /**
+     * Compose one check-stage host's check, fix or format command. The full
+     * plugin configuration accompanies the command; optional threading, timing
+     * and project-context fields require that host's declared support.
+     *
+     * @evidence contracts/common.md#principled-implementation Subcommand selection follows format/fix options while capability-gated fields preserve the selected host's accepted protocol.
+     * @evidence contracts/common.md#clear-and-simple-design Shared core fields are assembled before small helpers add threading and timing, separating host capability policy from compiler argv.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional flags use descriptor capabilities rather than special plugin names or monkey-patched foreign flag sets.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains command effects, full configuration delivery and capability-dependent fields.
+     * @evidence contracts/portability.md#os-neutral-implementation cwd and output locations retain native path semantics; each protocol flag is a separate argv element and plugin configuration is JSON, not shell text.
+     * @evidence contracts/performance.md#efficient-algorithms Composition serializes plugin count/name/stage/config fields; capability-gated timing selection projects the unexpanded forwarded argv frame with token/name/value costs. Optional project-context encoding and native output-path resolution add text work; returned storage follows argv bytes.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Building one command does not coordinate completed or in-flight execution across consumers.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No sidecar or persistent argument cache is owned by this composer.
+     */
+    function createNativeCheckArgs(execution: ReturnType<typeof BuildExecution.resolveExecutionContext>, options: TtscBuildOptions, plugin: ITtscLoadedNativePlugin): string[];
+    /**
+     * Build the argv of a native host's `project-inputs` query, which reports the
+     * non-TypeScript files (documents, schemas, configs) the host's rules read,
+     * so watch and cache invalidation can observe them.
+     *
+     * The caller must check projectInputs capability before launching this query.
+     *
+     * @evidence contracts/common.md#principled-implementation Project selection and complete plugin configuration let the host report its actual rule inputs; optional project context is sent only when supported.
+     * @evidence contracts/common.md#clear-and-simple-design This composer owns query argv while the discovery operation owns capability selection, execution and snapshot validation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The explicit project-inputs protocol queries declared dependencies instead of guessing files from plugin names or dropping unsupported inputs.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains non-TypeScript dependencies, invalidation purpose and the caller's capability premise.
+     * @evidence contracts/portability.md#os-neutral-implementation Selected tsconfig/cwd spellings travel as separate native argv fields; no slash rewriting or shell construction is applied to paths.
+     * @evidence contracts/performance.md#efficient-algorithms Plugin descriptors are projected and JSON-encoded once, with plugin count, name/stage/config serialization costs. Optional project-context encoding and composed native path-field text add work/storage; fixed field count does not make payload cost constant.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Query composition establishes no cross-request reuse of host dependency discovery.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned argv has caller ownership; this function acquires no native resource or retained snapshot.
+     */
+    function createNativeProjectInputsArgs(execution: ReturnType<typeof BuildExecution.resolveExecutionContext>, plugin: ITtscLoadedNativePlugin): string[];
+    /**
+     * The `--diagnostics` timing label of one transform-host run, naming every
+     * plugin that shared the host so a slow run can be attributed.
+     *
+     * @evidence contracts/common.md#principled-implementation Names of all selected participants form one label for the shared execution, rather than attributing its duration to only one plugin.
+     * @evidence contracts/common.md#clear-and-simple-design A single name projection and join supplies timing attribution without coupling labels to process selection.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Participant names come from the actual loaded selection, not a fixed benchmark label or special plugin list.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies the shared-host timing purpose and attribution scope.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Formatting participant names touches no native path, filesystem or process boundary.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms One projection and join cost O(P plus participant-name/output bytes) for P plugins, with no repeated string-prefix rebuilding.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A label formatter coordinates no shared computation beyond the supplied participant list.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The formatter returns text without retaining selection history or handles.
+     */
+    function transformHostTimingLabel(plugins: readonly ITtscLoadedNativePlugin[]): string;
+    /**
+     * Serialize the plugin list to a compact JSON string for `--plugins-json=`.
+     * Only the fields the native binary protocol requires are included.
+     *
+     * @evidence contracts/common.md#principled-implementation Projection retains config, name and stage, the protocol's declared plugin descriptor fields, without serializing host-loader implementation details.
+     * @evidence contracts/common.md#clear-and-simple-design One explicit projection defines the JSON wire representation separately from in-memory plugin metadata.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Standard JSON encoding preserves configuration structure without handcrafted quoting or mutation of foreign descriptors.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the compact protocol purpose and deliberate field restriction.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation JSON descriptor serialization accesses no native filesystem or process and applies no path normalization.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms One projection visits P plugins and standard JSON serialization traverses config/name/stage values into returned bytes. Custom getters/toJSON and exceptional or cyclic config values follow ordinary JSON semantics and can add work or throw; no serialization work ceiling is supplied here. Only required descriptor fields are explicitly projected.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable plugin configuration is serialized for the current invocation without establishing cross-request equivalence.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local projections become returned text; no persistent descriptor cache or handle is retained.
+     */
+    function serializeNativePlugins(plugins: readonly ITtscLoadedNativePlugin[]): string;
+}