# Jai plugin for IntelliJ IDEA

Support for the [Jai](https://jai.community) programming language.
Everything here is derived from the local Jai distribution at `~/.local/jai`,
never from online material (see `AGENTS.md`).

## What works today

- `.jai` file type with its own icon
- Syntax highlighting: keywords, built-in type names, compiler directives
  (`#import`, `#run`, …), notes (`@Cleanup`), numbers (hex / binary / hexfloat /
  `_` separators), strings, here-strings (`#string DONE … DONE`), nesting block
  comments, operators, `---`, `$`/`$$`, `it` / `it_index`
- Grammar-Kit parser and PSI for the full local 714-file corpus
- Structure view and folding for blocks, comments, and here-strings
- Colour settings page (**Settings → Editor → Color Scheme → Jai**)
- Comment / uncomment (`//` and nesting `/* */`)
- Brace matching, including the Jai-only `.{` struct-literal and `.[`
  array-literal openers
- Completion for keywords, directives, Jai module/file paths, visible
  same-file or imported declarations, procedure parameters, and members of
  imported module aliases
- Project settings for ordered Jai module/import roots
- Go-to-definition for procedures and types in the same file and through
  `#import`/`#load`, including configured external roots
- Indexed external Jai roots so find-usages can cross project/library boundaries
- Rename and find-usages for declaration names and their resolved references
- PSI-aware formatting for operator and punctuation spacing, block indentation,
  directive flags, and opaque `#asm` bodies; formatting is idempotent across the
  full local corpus
- Inspection warnings for unresolved `#import` and `#load` module/file paths

Remaining code-insight gaps include completion and symbol resolution for struct
fields and other type-qualified members. Additional inspections and compiler
integration are planned later.
See `docs/BUILD_PLAN.md` for the phase plan.

## Install it locally

```bash
./jaigradle buildPlugin
# -> build/distributions/intellijai-1.0.0-SNAPSHOT.zip
```

In the IDE: **Settings → Plugins → ⚙ → Install Plugin from Disk…**, pick that
ZIP, restart when prompted. Requires build 253 (2025.3) or newer; verified
compatible with IU-253, IU-261 and IU-262 by the JetBrains Plugin Verifier.

To try it, open any file from `~/.local/jai/how_to/`. Configure additional
module/import directories under **Settings → Languages & Frameworks → Jai**;
configured roots are searched in order and indexed as Jai library sources.

Uninstall or update the same way — installing a new ZIP over the old one
replaces it.

## Develop

```bash
./jaigradle test     # or ./jaitest, which reports the JUnit XML
./jaigradle check    # full verification
```

Never call `./gradlew` directly: there is no JDK on `PATH`, and `./jaigradle`
resolves one via mise first. Read `AGENTS.md` before changing anything.

Key docs:

| File | What it is |
| --- | --- |
| `AGENTS.md` | how to work in this repo; current state |
| `docs/JAI_LANGUAGE_REFERENCE.md` | the language, transcribed from the compiler |
| `docs/BUILD_PLAN.md` | phased plan and testing strategy |

Local IntelliJ references are available in `~/programming/thirdparty`:

- `fortran-plugin` — a simple language plugin to use as reference.
- `intellij-elixir` — a more complex plugin to use as reference.
- `intellij-sdk-docs` — local versions of the IntelliJ SDK documentation.