intellijai/AGENTS.md

# AGENTS.md — Jai IntelliJ Plugin

Orientation for agents working on this repo. Read this first.

**Goal:** an IntelliJ plugin for the **Jai** programming language.

**Hard rule:** do **not** research Jai online — public material is outdated and
wrong. The only source of truth is the local install at `~/.local/jai`
(`how_to/`, `modules/`, `examples/`). Researching *IntelliJ plugin development*
online is fine and encouraged.

---

## Run anything with `./jaigradle`

```bash
./jaigradle test     # unit tests
./jaigradle check    # full verification
./jaigradle tasks    # discover tasks
```

**Never call `./gradlew` directly.** There is no JDK on `PATH` and `JAVA_HOME`
is unset in a fresh shell. `./jaigradle` resolves the JDK via mise, then
delegates. It works from an environment with no Java at all.

Do not try to fix this with `org.gradle.java.home` in `gradle.properties` —
already tried, it does not work, because `gradlew` is a shell script that needs
a JVM to launch *itself* before it ever reads that property.

**Java must be 21+.** The IntelliJ Platform test-framework jars are Java 21
bytecode (class major version 65); on JDK 17 every test fails with
`UnsupportedClassVersionError`. `mise.toml` pins `java = "temurin-21"`.

Note that `./jaigradle compileKotlin` **passes on JDK 17** — the template
sources never touch the test framework. Compiling is not evidence the toolchain
is correct. Run tests.

---

## Verify with the JUnit XML, not the exit code

A green `test` task does not prove tests ran. Always confirm:

```bash
cat build/test-results/test/*.xml | head -3
```

Look for `tests="N"` with `failures="0" errors="0"` and **N > 0**.

Last verified state (all green):

```text
TEST-dev.hgh.HarnessSmokeTest.xml -> tests=2 skipped=0 failures=0 errors=0
```

---

## Current state

### Done

- `docs/JAI_LANGUAGE_REFERENCE.md` — language reference derived from
  `~/.local/jai`, keywords/tokens transcribed from the compiler's own lexer.
  **Read this before writing any lexer or parser code.**
- `docs/BUILD_PLAN.md` — phased plan, testing strategy, risks, open questions.
- `mise.toml` → `java = "temurin-21"` (was 17, which was broken).
- `jaigradle` — JDK-resolving Gradle wrapper. Executable, verified.
- `src/test/kotlin/dev/hgh/HarnessSmokeTest.kt` — proves the platform boots
  headlessly. **If this fails, no other test can be trusted.**

### Not done — pick up here

1. **`git init`.** Still not a repository. Do this first; there is no rollback
   point right now. Add `.kotlin` to `.gitignore` (currently untracked and
   unignored).
2. **Strip the template.** `src/main/kotlin/MyToolWindowFactory.kt`,
   `MyMessageBundle.kt`, `messages/MyMessageBundle.properties`, and the
   `toolWindow` registration + `resource-bundle` in `plugin.xml` are all
   JetBrains scaffold and must go. `plugin.xml` metadata (name, vendor,
   description) is still placeholder text.
3. **Phase 1: lexer** — see the plan.

### Open questions for the user (unanswered)

Scope (Phases 0–4 vs 0–7), compiler integration, target IDEs, JDK policy. See
`docs/BUILD_PLAN.md` §6. Scope is the one that most affects the work.

---

## Architecture decisions already made

Both are justified in `docs/BUILD_PLAN.md` §2. Do not silently reverse them.

- **Hand-written lexer, not JFlex.** Jai here-strings (`#string DONE … DONE`)
  have a *runtime-captured* terminator, which a DFA generator cannot express.
  Nested block comments need a depth counter. Both would end up as hand-written
  Java inside JFlex actions anyway.
- **Grammar-Kit BNF for parser + PSI.** Verified headless: the plugin ID is
  `org.jetbrains.intellij.platform.grammarkit`, bundled in the IntelliJ Platform
  Gradle Plugin since 2.12.0 (we run 2.18.1). `generateLexer` / `generateParser`
  already appear in `./jaigradle tasks --all` — no extra dependency needed.
- **Ship highlighting before the parser.** Highlighting needs only the lexer.

---

## The test corpus is the main asset

`~/.local/jai` holds **714 `.jai` files, 16.4 MB** of real code by the language
authors. Use it as the primary correctness gate instead of hand-written samples.

The highest-value assertion, per the plan: lex every file and check the
concatenation of all token texts reproduces the source **byte for byte**. An
IntelliJ lexer must tile its input with no gaps or overlaps, so this single
invariant over 16 MB catches nearly every lexer bug — with no fixture boot and
no human review. Also assert no `BAD_CHARACTER` and that every `advance()`
strictly increases the offset (catches infinite loops, which hang the IDE rather
than failing visibly).

Same idea later: zero `PsiErrorElement` across the corpus for the parser;
formatting is idempotent for the formatter.

---

## Environment gotchas

- **Stale Gradle daemons.** Mixing JDK 17 and 21 daemons caused
  `Timeout waiting to lock journal cache`. Fix: `./jaigradle --stop`.
- **`timeout` does not exist on this macOS box.** Do not use it in scripts.
- **Noisy test stderr.** Fixture runs log Vue/JS `PluginException`s from bundled
  plugins. Tests pass regardless, but real failures can be buried — check the
  XML. Narrowing the test fixture later would help.
- **`runIde` is never required.** Everything is verifiable headlessly; that is a
  hard project requirement, not a preference. Do not ask the user to open an IDE
  to check your work.

---

## Working agreement

- Verify claims by running commands; prefer empirical checks over docs. Several
  plan decisions came from testing assumptions that turned out false.
- Keep the working tree clean — revert throwaway probes.
- Generated sources (once Grammar-Kit is wired up) go in `src/main/gen`, are
  committed, and are **never hand-edited**; regenerate instead.
- Update this file when project state changes.