Scaffold IPC-based API

.github/workflows/ci.yml

@@ -23,6 +23,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
       - uses: ./.github/actions/setup-go
         with:
           cache-name: build
@@ -36,6 +37,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
 
       - run: npm ci
 
@@ -90,6 +92,7 @@ jobs:
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
         with:
           node-version: 'lts/*'
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
       - uses: ./.github/actions/setup-go
         with:
           cache-name: test
@@ -103,7 +106,16 @@ jobs:
 
       - name: Tests
         id: test
-        run: npx hereby test:all
+        run: npx hereby test
+
+      - name: Benchmarks
+        run: npx hereby test:benchmarks
+
+      - name: Tools Tests
+        run: npx hereby test:tools
+
+      - name: API Tests
+        run: npx hereby test:api
 
       - run: git add .
 
@@ -150,6 +162,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
       - uses: ./.github/actions/setup-go
         with:
           cache-name: lint${{ (matrix.noembed && '-noembed') || ''}}
@@ -163,6 +176,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
       - uses: ./.github/actions/setup-go
         with:
           cache-name: format
@@ -179,6 +193,7 @@ jobs:
         with:
           submodules: true
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
       - uses: ./.github/actions/setup-go
         with:
           cache-name: generate
@@ -208,6 +223,7 @@ jobs:
         with:
           submodules: true
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
       - uses: ./.github/actions/setup-go
         with:
           cache-name: smoke
@@ -239,6 +255,7 @@ jobs:
         with:
           submodules: true
       - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
+      - uses: dtolnay/rust-toolchain@fcf085fcb4b4b8f63f96906cd713eb52181b5ea4 # stable
       - uses: ./.github/actions/setup-go
         with:
           cache-name: baselines

Herebyfile.mjs

@@ -314,18 +314,37 @@ async function runTestTools() {
     await $test({ cwd: path.join(__dirname, "_tools") })`${gotestsum("tools")} ./...`;
 }
 
+async function runTestAPI() {
+    await $`npm run -w @typescript/api test`;
+}
+
 export const testTools = task({
     name: "test:tools",
     run: runTestTools,
 });
 
+export const buildAPITests = task({
+    name: "build:api:test",
+    run: async () => {
+        await $`npm run -w @typescript/api build:test`;
+    },
+});
+
+export const testAPI = task({
+    name: "test:api",
+    dependencies: [tsgo, buildAPITests],
+    run: runTestAPI,
+});
+
 export const testAll = task({
     name: "test:all",
+    dependencies: [buildAPITests],
     run: async () => {
         // Prevent interleaving by running these directly instead of in parallel.
         await runTests();
         await runTestBenchmarks();
         await runTestTools();
+        await runTestAPI();
     },
 });
 

README.md

@@ -7,7 +7,7 @@ Interested developers can clone and run locally to try out things as they become
 
 ## How to Build and Run
 
-This repo uses [Go 1.24 or higher](https://go.dev/dl/), [Node.js with npm](https://nodejs.org/), and [`hereby`](https://www.npmjs.com/package/hereby).
+This repo uses [Go 1.24 or higher](https://go.dev/dl/), [Rust 1.85 or higher](https://www.rust-lang.org/tools/install), [Node.js with npm](https://nodejs.org/), and [`hereby`](https://www.npmjs.com/package/hereby).
 
 For tests and code generation, this repo contains a git submodule to the main TypeScript repo pointing to the commit being ported.
 When cloning, you'll want to clone with submodules:

_packages/api/package.json

@@ -0,0 +1,51 @@
+{
+    "private": true,
+    "name": "@typescript/api",
+    "version": "1.0.0",
+    "type": "module",
+    "imports": {
+        "#symbolFlags": {
+            "@typescript/source": {
+                "types": "./src/symbolFlags.enum.ts",
+                "default": "./src/symbolFlags.ts"
+            },
+            "types": "./dist/symbolFlags.enum.d.ts",
+            "default": "./dist/symbolFlags.js"
+        },
+        "#typeFlags": {
+            "@typescript/source": {
+                "types": "./src/typeFlags.enum.ts",
+                "default": "./src/typeFlags.ts"
+            },
+            "types": "./dist/typeFlags.enum.d.ts",
+            "default": "./dist/typeFlags.js"
+        }
+    },
+    "exports": {
+        ".": {
+            "@typescript/source": "./src/api.ts",
+            "default": "./dist/api.js"
+        },
+        "./fs": {
+            "@typescript/source": "./src/fs.ts",
+            "default": "./dist/fs.js"
+        },
+        "./proto": {
+            "@typescript/source": "./src/proto.ts",
+            "default": "./dist/proto.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc -b",
+        "build:test": "tsc -b test",
+        "bench": "node --experimental-strip-types --no-warnings --conditions @typescript/source test/api.bench.ts",
+        "test": "node --test --experimental-strip-types --no-warnings --conditions @typescript/source ./test/**/*.test.ts"
+    },
+    "devDependencies": {
+        "tinybench": "^3.1.1"
+    },
+    "dependencies": {
+        "@typescript/ast": "1.0.0",
+        "libsyncrpc": "github:microsoft/libsyncrpc#bb02d84"
+    }
+}

_packages/api/src/api.ts

@@ -0,0 +1,179 @@
+/// <reference path="./node.ts" preserve="true" />
+import { SymbolFlags } from "#symbolFlags";
+import { TypeFlags } from "#typeFlags";
+import type {
+    Node,
+    SourceFile,
+} from "@typescript/ast";
+import { Client } from "./client.ts";
+import type { FileSystem } from "./fs.ts";
+import { RemoteSourceFile } from "./node.ts";
+import { ObjectRegistry } from "./objectRegistry.ts";
+import type {
+    ConfigResponse,
+    ProjectResponse,
+    SymbolResponse,
+    TypeResponse,
+} from "./proto.ts";
+
+export { SymbolFlags, TypeFlags };
+
+export interface APIOptions {
+    tsserverPath: string;
+    cwd?: string;
+    logFile?: string;
+    fs?: FileSystem;
+}
+
+export class API {
+    private client: Client;
+    private objectRegistry: ObjectRegistry;
+    constructor(options: APIOptions) {
+        this.client = new Client(options);
+        this.objectRegistry = new ObjectRegistry(this.client);
+    }
+
+    parseConfigFile(fileName: string): ConfigResponse {
+        return this.client.request("parseConfigFile", { fileName });
+    }
+
+    loadProject(configFileName: string): Project {
+        const data = this.client.request("loadProject", { configFileName });
+        return this.objectRegistry.getProject(data);
+    }
+
+    echo(message: string): string {
+        return this.client.echo(message);
+    }
+
+    echoBinary(message: Uint8Array): Uint8Array {
+        return this.client.echoBinary(message);
+    }
+
+    close(): void {
+        this.client.close();
+    }
+}
+
+export class DisposableObject {
+    private disposed: boolean = false;
+    protected objectRegistry: ObjectRegistry;
+    constructor(objectRegistry: ObjectRegistry) {
+        this.objectRegistry = objectRegistry;
+    }
+    [globalThis.Symbol.dispose](): void {
+        this.objectRegistry.release(this);
+        this.disposed = true;
+    }
+    dispose(): void {
+        this[globalThis.Symbol.dispose]();
+    }
+    isDisposed(): boolean {
+        return this.disposed;
+    }
+    ensureNotDisposed(): this {
+        if (this.disposed) {
+            throw new Error(`${this.constructor.name} is disposed`);
+        }
+        return this;
+    }
+}
+
+export class Project extends DisposableObject {
+    private decoder = new TextDecoder();
+    private client: Client;
+
+    id: string;
+    configFileName!: string;
+    compilerOptions!: Record<string, unknown>;
+    rootFiles!: readonly string[];
+
+    constructor(client: Client, objectRegistry: ObjectRegistry, data: ProjectResponse) {
+        super(objectRegistry);
+        this.id = data.id;
+        this.client = client;
+        this.loadData(data);
+    }
+
+    loadData(data: ProjectResponse): void {
+        this.configFileName = data.configFileName;
+        this.compilerOptions = data.compilerOptions;
+        this.rootFiles = data.rootFiles;
+    }
+
+    reload(): void {
+        this.ensureNotDisposed();
+        this.loadData(this.client.request("loadProject", { configFileName: this.configFileName }));
+    }
+
+    getSourceFile(fileName: string): SourceFile | undefined {
+        this.ensureNotDisposed();
+        const data = this.client.requestBinary("getSourceFile", { project: this.id, fileName });
+        return data ? new RemoteSourceFile(data, this.decoder) as unknown as SourceFile : undefined;
+    }
+
+    getSymbolAtLocation(node: Node): Symbol | undefined;
+    getSymbolAtLocation(nodes: readonly Node[]): (Symbol | undefined)[];
+    getSymbolAtLocation(nodeOrNodes: Node | readonly Node[]): Symbol | (Symbol | undefined)[] | undefined {
+        this.ensureNotDisposed();
+        if (Array.isArray(nodeOrNodes)) {
+            const data = this.client.request("getSymbolsAtLocations", { project: this.id, locations: nodeOrNodes.map(node => node.id) });
+            return data.map((d: SymbolResponse | null) => d ? this.objectRegistry.getSymbol(d) : undefined);
+        }
+        const data = this.client.request("getSymbolAtLocation", { project: this.id, location: (nodeOrNodes as Node).id });
+        return data ? this.objectRegistry.getSymbol(data) : undefined;
+    }
+
+    getSymbolAtPosition(fileName: string, position: number): Symbol | undefined;
+    getSymbolAtPosition(fileName: string, positions: readonly number[]): (Symbol | undefined)[];
+    getSymbolAtPosition(fileName: string, positionOrPositions: number | readonly number[]): Symbol | (Symbol | undefined)[] | undefined {
+        this.ensureNotDisposed();
+        if (typeof positionOrPositions === "number") {
+            const data = this.client.request("getSymbolAtPosition", { project: this.id, fileName, position: positionOrPositions });
+            return data ? this.objectRegistry.getSymbol(data) : undefined;
+        }
+        const data = this.client.request("getSymbolsAtPositions", { project: this.id, fileName, positions: positionOrPositions });
+        return data.map((d: SymbolResponse | null) => d ? this.objectRegistry.getSymbol(d) : undefined);
+    }
+
+    getTypeOfSymbol(symbol: Symbol): Type | undefined;
+    getTypeOfSymbol(symbols: readonly Symbol[]): (Type | undefined)[];
+    getTypeOfSymbol(symbolOrSymbols: Symbol | readonly Symbol[]): Type | (Type | undefined)[] | undefined {
+        this.ensureNotDisposed();
+        if (Array.isArray(symbolOrSymbols)) {
+            const data = this.client.request("getTypesOfSymbols", { project: this.id, symbols: symbolOrSymbols.map(symbol => symbol.ensureNotDisposed().id) });
+            return data.map((d: TypeResponse | null) => d ? this.objectRegistry.getType(d) : undefined);
+        }
+        const data = this.client.request("getTypeOfSymbol", { project: this.id, symbol: (symbolOrSymbols as Symbol).ensureNotDisposed().id });
+        return data ? this.objectRegistry.getType(data) : undefined;
+    }
+}
+
+export class Symbol extends DisposableObject {
+    private client: Client;
+    id: string;
+    name: string;
+    flags: SymbolFlags;
+    checkFlags: number;
+
+    constructor(client: Client, objectRegistry: ObjectRegistry, data: SymbolResponse) {
+        super(objectRegistry);
+        this.client = client;
+        this.id = data.id;
+        this.name = data.name;
+        this.flags = data.flags;
+        this.checkFlags = data.checkFlags;
+    }
+}
+
+export class Type extends DisposableObject {
+    private client: Client;
+    id: string;
+    flags: TypeFlags;
+    constructor(client: Client, objectRegistry: ObjectRegistry, data: TypeResponse) {
+        super(objectRegistry);
+        this.client = client;
+        this.id = data.id;
+        this.flags = data.flags;
+    }
+}