# Native TypeScript backend

The language server requires the in-tree [TypeScript patch](typescript/README.md),
pinned to upstream commit `b5c34ba0c61a756c8abaf133236dddf982c27f45`
(version `7.1.0-dev.20261013.1`). The executable is a trusted host tool;
filesystem callbacks are not an OS sandbox. Project code and compiler plugins
are not executed.

## Build

Build separately from Avril; Node/npm installation is not required. These
commands require Git, Bash, and Go and start at the Avril repository root:

```sh
typescript_src=$(mktemp -d)
git clone --filter=blob:none --no-checkout \
  https://github.com/microsoft/TypeScript.git "$typescript_src"
git -C "$typescript_src" checkout --detach b5c34ba0c61a756c8abaf133236dddf982c27f45
bash lib/lsp/typescript/build.sh "$typescript_src" "/absolute/path/to/avril-tsc"
cargo build --locked -p avril-cli --bin avril
```

If Go is not on PATH, replace the `build.sh` invocation with:

```sh
nix shell nixpkgs#go --command bash lib/lsp/typescript/build.sh \
  "$typescript_src" "/absolute/path/to/avril-tsc"
```

The upstream Go module selects its toolchain and may download it. Standard-library
declarations are embedded in the binary, so the temporary source checkout is not
needed at runtime. The build script verifies the revision and patch applicability
before modifying the checkout, runs native tests, and leaves the checkout
patched; use a fresh checkout for each build.

For editor installation and user settings, follow the
[VS Code setup](../../editors/vscode/README.md#build-and-install). Configure
`avril.lsp.backend` with the expanded absolute path to this binary—not an npm
TypeScript package, a directory, or a JavaScript `tsc.js` file. The extension
starts `avril lsp` for you.

The frontend checks both the TypeScript version and bridge protocol version.
An unpatched binary fails LSP initialization with installation guidance.
`avril check` still works with the pinned stock API, but using the same patched
binary for checking and editing is recommended.

## Contract

Avril creates immutable API snapshots, supplies source text, compiler-option
groups and authoritative static resolution tables, and denies unrelated filesystem
reads. Unknown module imports remain unresolved rather than falling back to
compiler filesystem discovery.
The patch invokes native language-service providers on those exact programs.
It does not start the stock LSP's config discovery, package discovery, typings
installation, or content-mapper execution.

The bridge uses UTF-16 positions independently of the ordinary API's UTF-8
snapshot converter. Results contain LSP objects rather than AST/checker handles.
Rust translates compiler document identities, binds deferred items to their
originating generation, and rejects edit sets touching immutable sources.
The [patch README](typescript/README.md) describes the wire protocol and limits.

## Validate

Start at the Avril repository root, with `typescript_src` still pointing to the
patched checkout from the build above:

```sh
AVRIL_TEST_TYPESCRIPT="/absolute/path/to/avril-tsc" cargo nextest run --workspace
cargo test --workspace --doc
cd "$typescript_src/tsc"
go test ./internal/api ./internal/ipc ./internal/ls/autoimport
```

Backend-dependent Rust tests return early without `AVRIL_TEST_TYPESCRIPT`;
a run without it does not validate this integration. `native_api` independently
checks the underlying stock API contracts. CLI LSP tests exercise the patched
bridge through framed editor messages, including resolution denial, live edits,
completion resolve, signatures, navigation, rename, and cancellation.

VS Code unit and actual editor-host tests are separate; see
[editor validation](../../editors/vscode/README.md#validation).