|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to AI coding assistants when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is the official ReScript VSCode extension, providing language support for ReScript (.res/.resi files) in Visual Studio Code. The project uses a Language Server Protocol (LSP) architecture with a TypeScript client/server and native OCaml binaries for analysis. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +### Key Components |
| 12 | + |
| 13 | +- **client/**: VSCode extension client (`client/src/extension.ts`) - handles UI, commands, and language client initialization |
| 14 | +- **server/**: Language Server (`server/src/server.ts`, `server/src/cli.ts`) - implements LSP features, communicates with ReScript compiler |
| 15 | +- **analysis/**: Native OCaml binary for code analysis, hover, autocomplete, and other language features. This is for older ReScript versions only (ReScript 11 and below). New features are usually only implemented in the rescript compiler monorepo. |
| 16 | +- **tools/**: ReScript tools binary for additional functionality like interface file generation. This is also for older ReScript versions only (ReScript 11 and below). New features are usually only implemented in the rescript compiler monorepo. |
| 17 | +- **grammars/**: TextMate grammar files for syntax highlighting |
| 18 | +- **snippets.json**: Code snippets for common ReScript patterns |
| 19 | + |
| 20 | +### Build System |
| 21 | + |
| 22 | +The project uses: |
| 23 | +- **dune**: For building OCaml components (analysis & tools) |
| 24 | +- **esbuild**: For bundling TypeScript client/server |
| 25 | +- **npm**: For JavaScript/TypeScript dependencies |
| 26 | +- **TypeScript**: For type checking the client/server code |
| 27 | + |
| 28 | +## Development Commands |
| 29 | + |
| 30 | +### Initial Setup |
| 31 | +```bash |
| 32 | +npm install # Install all dependencies including client/server |
| 33 | +opam switch 5.2.0 # Install OCaml switch (if not already done) |
| 34 | +opam install . --deps-only # Install OCaml dependencies |
| 35 | +``` |
| 36 | + |
| 37 | +### Building |
| 38 | +```bash |
| 39 | +make build # Build OCaml binaries and copy to root |
| 40 | +npm run compile # Compile TypeScript (client & server) |
| 41 | +npm run bundle # Bundle for production (esbuild) |
| 42 | +npm run vscode:prepublish # Clean and bundle (used for publishing) |
| 43 | +``` |
| 44 | + |
| 45 | +### Development |
| 46 | +```bash |
| 47 | +npm run watch # Watch TypeScript compilation |
| 48 | +make -C analysis test # Run analysis tests |
| 49 | +make -C tools/tests test # Run tools tests |
| 50 | +make test # Run all tests |
| 51 | +``` |
| 52 | + |
| 53 | +### Code Quality |
| 54 | +```bash |
| 55 | +make format # Format OCaml (dune) and JS/TS (prettier) |
| 56 | +make checkformat # Check formatting without modifying |
| 57 | +make clean # Clean build artifacts |
| 58 | +``` |
| 59 | + |
| 60 | +### Running the Extension in Development |
| 61 | +1. Open the project in VSCode |
| 62 | +2. Press F5 to launch a new VSCode window (Extension Development Host) |
| 63 | +3. Open a ReScript project to test the extension |
| 64 | + |
| 65 | +## Key Files |
| 66 | + |
| 67 | +### Configuration |
| 68 | +- `package.json`: Extension manifest, commands, settings, and scripts |
| 69 | +- `rescript.configuration.json`: Editor configuration for ReScript files |
| 70 | +- `client/src/extension.ts`: Extension entry point and client initialization |
| 71 | +- `server/src/server.ts`: Language server implementation |
| 72 | +- `server/src/cli.ts`: CLI entry point for the language server |
| 73 | + |
| 74 | +### OCaml Components |
| 75 | +- `analysis/`: Code analysis binary (hover, autocomplete, etc.) |
| 76 | +- `tools/`: ReScript tools binary (interface generation, etc.) |
| 77 | + |
| 78 | +### Language Features |
| 79 | +- **LSP Features**: hover, goto definition, find references, rename, autocomplete |
| 80 | +- **Code Analysis**: dead code detection, exception analysis (via reanalyze) |
| 81 | +- **Build Integration**: compile diagnostics, status indicators |
| 82 | +- **Commands**: interface creation, file switching, compiled JS opening |
| 83 | + |
| 84 | +## Testing |
| 85 | + |
| 86 | +The project has several test suites: |
| 87 | +- `analysis/tests/`: Tests for the analysis binary |
| 88 | +- `tools/tests/`: Tests for ReScript tools |
| 89 | +- `analysis/tests-incremental-typechecking/`: Incremental typechecking tests |
| 90 | +- `analysis/tests-generic-jsx-transform/`: JSX transformation tests |
| 91 | + |
| 92 | +## Project Structure Notes |
| 93 | + |
| 94 | +- The extension supports both `.res` (implementation) and `.resi` (interface) files |
| 95 | +- Uses VSCode Language Client protocol for communication between client and server |
| 96 | +- Native binaries are cross-platform (darwin, linux, win32) and included in the extension |
| 97 | +- Supports workspace configurations and monorepo structures |
| 98 | +- Incremental type checking can be enabled for better performance on large projects |
| 99 | +- As mentioned above the native OCaml binaries here are only here for backwards-compatibility with ReScript versions 11 or below. Since ReScript 12 both `analysis` and `tools` are part of the ReScript compiler monorepo, thus refrain from changing them too much (bugfixes that need to be ported are ok). |
0 commit comments