Merge branch 'main' into make-codegen-incremental

Author: weswigham

.github/skills/api-client/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: api-client
+description: Instructions for working on the API client in ./packages/typescript
+---
+
+## Code comments
+
+The user may tell you to reference Strada (the old TypeScript codebase) for implementation, but your code comments should not acknowledge that this codebase is a port of anything else. Comments should stand on their own and describe the code in the current codebase. Never say "Mirrors TypeScript's 'foo' function" or "...like the classic API's 'Bar' type."
+
+## Unnecessary spread and `exactOptionalPropertyTypes`
+
+Never write code like `...(options ? { snapshot: options.snapshot } : {})`. All optional properties should tolerate `undefined`. If `--exactOptionalPropertyTypes` is forcing you to write code this way, fix the offending type. Rewriting as `if (options) foo.snapshot = options.snapshot` is not an acceptable workaround; always fix the type. As a rule, object types used in input positions should always define optional properties with `prop?: T | undefined` so this isn't a problem.

.github/workflows/ci.yml

@@ -93,6 +93,16 @@ jobs:
             os: windows
             coverage: true
             skip: ${{ github.event_name == 'merge_group' }}
+          - runner: ubuntu-26.04-arm
+            name: 'linux arm64'
+            os: linux
+            coverage: true
+            skip: ${{ github.event_name == 'merge_group' }}
+          - runner: windows-11-arm
+            name: 'windows arm64'
+            os: windows
+            coverage: true
+            skip: ${{ github.event_name == 'merge_group' }}
           - runner: macos-latest
             os: macos
             coverage: true
@@ -214,6 +224,7 @@ jobs:
       - run: npx hereby test:extension
       - run: npx hereby test:tools
       - run: npx hereby test:api
+      - run: npx hereby test:benchmarks:api
       - run: git add .
       - uses: codecov/codecov-action@0b35c9ecc4f0529d0eb674914510c22f85b196b4 # v7.1.0
         if: ${{ always() && matrix.config.coverage && github.event_name != 'merge_group' }}

Herebyfile.mjs

@@ -1512,7 +1512,7 @@ async function runTestBenchmarks() {
 
 export const testBenchmarks = task({
     name: "test:benchmarks",
-    description: "Runs all benchmarks.",
+    description: "Runs Go benchmarks once; excluded from validate.",
     run: runTestBenchmarks,
 });
 
@@ -1525,6 +1525,12 @@ async function runTestAPI() {
     await run("node", ["--conditions", "@typescript/source", "--test", "./test/**/*.test.ts"], { cwd: "./packages/typescript" });
 }
 
+async function runTestAPIBenchmarks() {
+    for (const variant of ["async", "sync", "generators"]) {
+        await run("node", ["--conditions", "@typescript/source", `./test/${variant}/api.bench.ts`, "--singleIteration"], { cwd: "./packages/typescript" });
+    }
+}
+
 export const testTools = task({
     name: "test:tools",
     description: "Runs all tests in the tools module.",
@@ -1564,6 +1570,13 @@ export const testAPI = task({
     run: runTestAPI,
 });
 
+export const testAPIBenchmarks = task({
+    name: "test:benchmarks:api",
+    description: "Runs async, sync, and generator API benchmarks once; excluded from validate.",
+    dependencies: [tsgo, buildAPITests],
+    run: runTestAPIBenchmarks,
+});
+
 export const testAll = task({
     name: "test:all",
     description: "Runs compiler, extension, benchmark, tools, and API tests. Codegen tests are opt-in via test:codegen.",
@@ -1575,6 +1588,7 @@ export const testAll = task({
         await runTestBenchmarks();
         await runTestTools();
         await runTestAPI();
+        await runTestAPIBenchmarks();
     },
 });
 
@@ -1703,7 +1717,7 @@ async function runFormat() {
 
 export const validate = task({
     name: "validate",
-    description: "Generates, builds, tests, lints, and formats the repo. Pass --api to include API tests, or --all to include all code generation and ancillary repository tests.",
+    description: "Generates, builds, tests, lints, and formats the repo. Pass --api to include API tests, or --all to include all code generation and ancillary repository tests Benchmarks are separate: test:benchmarks and test:benchmarks:api.",
     dependencies: [options.all ? generateAll : generate],
     run: async () => {
         await generateLibs(builtLocal);
@@ -1730,7 +1744,12 @@ export const validate = task({
             await runValidation("test:api", runTestAPI);
         }
         if (options.all) {
+<<<<<<< HEAD
             await runValidation("test:benchmarks", runTestBenchmarks);
+=======
+            await runGenerateExtension();
+            await runGenerateVendor();
+>>>>>>> main
             await runValidation("test:tools", runTestTools);
             await runValidation("test:smoke", runSmokeTest); // in CI this is run with `--race`
         }

package-lock.json

@@ -29,7 +29,7 @@
         "@jakebailey/dprint-plugin-gofumpt": "^0.0.18",
         "@types/node": "^22.20.1",
         "@unicode/unicode-15.1.0": "^1.6.17",
-        "adm-zip": "^0.6.0",
+        "adm-zip": "^0.6.1",
         "chokidar": "^5.0.0",
         "dprint": "^0.57.4",
         "dprint-plugin-yaml": "^0.6.0",

package.json

@@ -233,9 +233,9 @@ export type {
 };
 
 export interface TranspileOptions {
-    compilerOptions?: CompilerOptions;
-    fileName?: string;
-    reportDiagnostics?: boolean;
+    compilerOptions?: CompilerOptions | undefined;
+    fileName?: string | undefined;
+    reportDiagnostics?: boolean | undefined;
 }
 
 export interface TranspileOutput {
@@ -432,6 +432,10 @@ export class API<FromLSP extends boolean = false> implements FormatDiagnosticsHo
             snapshot: baseSnapshot.id,
             changes: toCreateSnapshotRequest(params),
         });
+        if (data.snapshot === baseSnapshot.id) {
+            await this.client.apiRequest("release", { snapshot: data.snapshot });
+            return baseSnapshot;
+        }
         this.sourceFileCache.retainForSnapshot(data.snapshot, baseSnapshot.id, data.changes);
         const snapshot = new Snapshot(
             data,
@@ -484,8 +488,8 @@ export class API<FromLSP extends boolean = false> implements FormatDiagnosticsHo
             throw new Error("Cannot use an inactive snapshot as a response base");
         }
         const data = await this.client.apiRequest("getCurrentLanguageServerSnapshot", {
-            ...(baseSnapshot ? { baseSnapshot: baseSnapshot.id } : {}),
-            ...(changes ? { changes } : {}),
+            baseSnapshot: baseSnapshot?.id,
+            changes,
         });
         if (baseSnapshot) {
             this.sourceFileCache.retainForSnapshot(data.snapshot, baseSnapshot.id, data.changes);
@@ -574,12 +578,13 @@ export class API<FromLSP extends boolean = false> implements FormatDiagnosticsHo
     /** Creates a program from current filesystem state. */
     async createProgram(
         rootFiles: readonly DocumentIdentifier[],
-        createProgramOptions: CreateProgramOptions,
+        compilerOptions: CompilerOptions,
+        createProgramOptions?: CreateProgramOptions,
     ): Promise<Program> {
         await this.ensureInitialized();
 
         const snapshot = await this.createSnapshot({
-            createPrograms: [{ rootFiles, options: createProgramOptions }],
+            createPrograms: [{ rootFiles, compilerOptions, options: createProgramOptions }],
         });
         const program = snapshot.operation.createdPrograms[0];
         if (!program) {
@@ -624,27 +629,47 @@ export class InternalAPI {
 type SnapshotUpdater = (params: CreateSnapshotParams) => Promise<Snapshot>; // @sync: type SnapshotUpdater = ((params: CreateSnapshotParams) => Snapshot) & { gen(params: CreateSnapshotParams): Generator<ProtocolRequest, Snapshot, ProtocolResponse["result"]>; };
 
 export interface SnapshotOperation {
-    readonly createdPrograms?: readonly Program<SyntheticProjectId>[];
-    readonly openedFiles?: readonly SnapshotOpenedFileOperation[];
+    readonly createdPrograms?: readonly Program<SyntheticProjectId>[] | undefined;
+    readonly openedFiles?: readonly SnapshotOpenedFileOperation[] | undefined;
 }
 
 export interface SnapshotOpenedFileOperation {
     readonly project: Project;
 }
 
+/** Replaces every element of a tuple while preserving its length and index structure. */
 type MapTupleTo<Tuple extends readonly unknown[], Result> = {
     readonly [Index in keyof Tuple]: Result;
 };
 
+/**
+ * Keeps `Tuple` as an inference target while contextually typing each element from
+ * `Elements`. The mapped intersection supplies nested completions and excess-property
+ * checks without widening an inferred tuple to an array.
+ */
+type ContextualizeTuple<
+    Tuple extends readonly unknown[] | undefined,
+    Elements extends readonly unknown[] | undefined,
+> =
+    & Tuple
+    & {
+        readonly [Index in keyof Tuple]: NonNullable<Elements>[number];
+    };
+
+/** Substitutes the operation arrays with contextually typed, tuple-preserving versions. */
 type SnapshotOperationParams<
     Params extends CreateSnapshotParams,
     CreatePrograms extends Params["createPrograms"],
     OpenFiles extends Params["openFiles"],
 > = Omit<Params, "createPrograms" | "openFiles"> & {
-    createPrograms?: CreatePrograms;
-    openFiles?: OpenFiles;
+    createPrograms?: ContextualizeTuple<CreatePrograms, Params["createPrograms"]> | undefined;
+    openFiles?: ContextualizeTuple<OpenFiles, Params["openFiles"]> | undefined;
 };
 
+/**
+ * Refines a snapshot's operation results to required tuples when the corresponding
+ * operation arrays were supplied, preserving their lengths for indexed access.
+ */
 type SnapshotForOperationResults<
     CreatePrograms extends CreateSnapshotParams["createPrograms"],
     OpenFiles extends CreateSnapshotParams["openFiles"],
@@ -655,6 +680,7 @@ type SnapshotForOperationResults<
         & (OpenFiles extends readonly unknown[] ? { readonly openedFiles: MapTupleTo<OpenFiles, SnapshotOpenedFileOperation>; } : unknown);
 };
 
+/** Derives the refined snapshot result type from a complete operation parameter type. */
 export type SnapshotForOperation<Params extends CreateSnapshotParams> = SnapshotForOperationResults<
     Params extends { createPrograms: infer CreatePrograms extends readonly unknown[]; } ? CreatePrograms : undefined,
     Params extends { openFiles: infer OpenFiles extends readonly unknown[]; } ? OpenFiles : undefined
@@ -706,8 +732,8 @@ export class Snapshot {
         }
 
         this.operation = {
-            ...(data.operation.createdPrograms ? { createdPrograms: data.operation.createdPrograms.map(projectId => this.requireProject(projectId).program) } : {}),
-            ...(data.operation.openedFiles ? { openedFiles: data.operation.openedFiles.map(result => ({ project: this.requireProject(result.project) })) } : {}),
+            createdPrograms: data.operation.createdPrograms?.map(projectId => this.requireProject(projectId).program),
+            openedFiles: data.operation.openedFiles?.map(result => ({ project: this.requireProject(result.project) })),
         };
 
         this.internal = new SnapshotInternalAPI(this.id, client);
@@ -1652,7 +1678,7 @@ export class Program<Id extends ProjectId = ProjectId> implements FormatDiagnost
             emitSkipped: response.emitSkipped,
             diagnostics: response.diagnostics,
             emittedFiles: response.emittedFiles,
-            ...(fileSystem ? { fileSystem } : {}),
+            fileSystem,
         };
     }
 

packages/typescript/src/api/async/api.ts

@@ -423,11 +423,11 @@ export interface EmitOutput {
 export interface ImportSymbolAction {
     readonly kind: "importSymbol";
     readonly symbol: Symbol;
-    readonly isValidTypeOnlyUseSite?: boolean;
+    readonly isValidTypeOnlyUseSite?: boolean | undefined;
 }
 
 export type ImportAdderAction = ImportSymbolAction;
 
 export interface GetImportEditsForSymbolsOptions {
-    readonly isValidTypeOnlyUseSite?: boolean;
+    readonly isValidTypeOnlyUseSite?: boolean | undefined;
 }

packages/typescript/src/api/async/types.ts

@@ -20,35 +20,35 @@ export interface FileSystemEntries {
 }
 
 export interface FileSystem {
-    directoryExists?: (directoryName: string) => boolean | undefined;
-    fileExists?: (fileName: string) => boolean | undefined;
-    getAccessibleEntries?: (directoryName: string) => FileSystemEntries | undefined;
+    directoryExists?: ((directoryName: string) => boolean | undefined) | undefined;
+    fileExists?: ((fileName: string) => boolean | undefined) | undefined;
+    getAccessibleEntries?: ((directoryName: string) => FileSystemEntries | undefined) | undefined;
     /**
      * Read a file's content.
      * - Return the file content as a `string` (including `""` for empty files).
      * - Return `null` to indicate the file does not exist (without falling back to the real FS).
      * - Return `undefined` to fall back to the real filesystem.
      */
-    readFile?: (fileName: string) => string | null | undefined;
-    realpath?: (path: string) => string | undefined;
-    writeFile?: (path: string, content: string) => void;
-    removeFile?: (path: string) => void;
+    readFile?: ((fileName: string) => string | null | undefined) | undefined;
+    realpath?: ((path: string) => string | undefined) | undefined;
+    writeFile?: ((path: string, content: string) => void) | undefined;
+    removeFile?: ((path: string) => void) | undefined;
 }
 
 /** The callback names supported by the Go server for virtual FS delegation. */
 export const fsCallbackNames = ["readFile", "fileExists", "directoryExists", "getAccessibleEntries", "realpath", "writeFile"] as const;
 
 export interface CreateFileSystemOptions {
     /** Complete directory listings. Full filesystems derive these from `files` when omitted. */
-    directories?: Record<string, RequestDirectoryEntries>;
-    symlinks?: Record<string, RequestSymlink>;
+    directories?: Record<string, RequestDirectoryEntries> | undefined;
+    symlinks?: Record<string, RequestSymlink> | undefined;
     /** Files or directory trees hidden from an underlying snapshot or host filesystem. */
-    removedPaths?: readonly string[];
+    removedPaths?: readonly string[] | undefined;
 }
 
 export interface CreateFileSystemWithLibOptions extends CreateFileSystemOptions {
     /** Default library directory used by a custom or non-embedded compiler executable. */
-    defaultLibraryPath?: string;
+    defaultLibraryPath?: string | undefined;
 }
 
 /**
@@ -91,8 +91,8 @@ export function createFileSystemWithLib(
     }
     return createRequestFileSystem("full", files, {
         symlinks,
-        ...(options.directories ? { directories: options.directories } : {}),
-        ...(options.removedPaths?.length ? { removedPaths: options.removedPaths } : {}),
+        directories: options.directories,
+        removedPaths: options.removedPaths?.length ? options.removedPaths : undefined,
     });
 }
 
@@ -122,9 +122,9 @@ function createRequestFileSystem(
     return {
         kind,
         files: fileRecord,
-        ...(directories ? { directories } : {}),
-        ...(options.symlinks ? { symlinks: options.symlinks } : {}),
-        ...(options.removedPaths?.length ? { removedPaths: [...options.removedPaths] } : {}),
+        directories,
+        symlinks: options.symlinks,
+        removedPaths: options.removedPaths?.length ? [...options.removedPaths] : undefined,
     };
 }