Skip to content

AGENTS.md

Latest commit

 

History

History
63 lines (45 loc) · 3.23 KB

AGENTS.md

File metadata and controls

63 lines (45 loc) · 3.23 KB
Raw

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.

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