tsgo — AGENTS.md

## Architecture Rules (Must Follow)

- Do NOT import `typescript-go` or `typescript-go/internal/...` directly from Effect code.
- Always import the shim packages (`github.com/microsoft/typescript-go/shim/...`) instead.
- Shims are auto-generated by `_tools/gen_shims` invoked by the `pnpm setup-repo`. The generated output must never be edited manually.
- All changes to typescript-go submodule should be as minimal as possible, and performed through the patches in the `_patches/` folder. The `typescript-go/` directory is reset during check runs, so direct edits there are ephemeral unless captured in `_patches/`.

## Reference Repositories

This repository uses local reference clones under `.repos/` for pattern and implementation research. These repositories are local-only working material and remain gitignored (`.repos/` is ignored by this repo) and bootstrapped by running `pnpm setup-repo`.

For Effect V4, setup manages three canonical reference clones:

- Local path: `.repos/effect-smol`
- Canonical origin: `https://github.com/Effect-TS/effect-smol`
- Local path: `.repos/effect-v3`
- Canonical origin: `https://github.com/Effect-TS/effect`
- Local path: `.repos/effect-language-service`
- Canonical origin: `https://github.com/Effect-TS/language-service`


## Code Validation Workflow
The following steps can be skipped if no go or typescript file has been changed in this branch, do not attempt any file change without user consent.
- run "pnpm setup-repo" first before the following steps to ensure that all the submodules are up to date and the codegen is up to date
- run "pnpm lint" to check and then you should fix linting errors
- run "pnpm check" to see if you should fix some type errors
- run "pnpm test" to validate that changes did not broke anything; note that those are quite long to run (15-20min).

## Push PR to GitHub Workflow
This workflow should be initiated only if asked by the user.

### 1. Ensure current branch
- The remote origin/main branch is not writeable, so if there are changes on the main branch, create a new one and work over there

### 2. Preliminary checks
- Run the Code Validation Workflow

### 3. Documentation checks
- If in the git changes against origin/main does not exists a new changeset file describing current changes, create a new one in the .changeset folder, the pattern is something like this:
```
---
"@effect/tsgo": ${patchType}
---

Description of the change with examples
```

"${patchType}" should be replaced by "patch" if the PR contains only bugfixes or small changes; or "minor" if new diagnostics, refactors or features are added.

### 4. Pushing the PR to GitHub
If all the preliminary checks pass, ask the user if some specific issue should be referenced, gather info on the issue and then create a new github PR for the changes that:
- Provide a description of what changed, ensure to read examples and tests related to the change to ensure full understanding of whats changed
- If the change involve refactors or diagnostic, provide an example of the feature added/changed


## Nix Flake

The repository now exposes a `flake.nix` for a self-contained language-server package built from pinned `typescript-go` and `TypeScript` sources plus this repo's patch set.

```bash
nix build .#effect-tsgo
nix run .#effect-tsgo
```