Skip to content

Commit 5878c7a

Browse files
serpentbladeserpentblade
committed
docs(08-06): document intellij plugin install + dev loop + dogfood feedback
- Add tools/intellij-plugin/README.md (108 lines) covering install path, dev loop, architecture link, dogfood feedback workflow, versioning, stable API contract, v1 limitations (D-11 SCSS editor-only caveat) - Append IDE Tooling section to repo-root README.md pointing at the plugin docs and the TextMate grammar fallback for Community editions - D-11 follow-up tracked in .planning/todos/pending/style-lang-compiler-followup.md (file on disk; .planning/ is gitignored on this repo)
1 parent 4d6f664 commit 5878c7a

2 files changed

Lines changed: 116 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,14 @@ pnpm test:e2e # Playwright suite (6 specs, 5 success criteria + OQ4)
107107

108108
Full rationale and alternatives considered in [`CLAUDE.md`](CLAUDE.md).
109109

110+
## IDE Tooling
111+
112+
A JetBrains IntelliJ Platform plugin (Rozie.js) provides syntax highlighting and JS/HTML/CSS language injection for `.rozie` files in IDEA Ultimate / WebStorm / PhpStorm / RubyMine / GoLand 2024.2+.
113+
114+
See [`tools/intellij-plugin/README.md`](tools/intellij-plugin/README.md) for installation, supported IDEs, dev loop, and dogfood feedback workflow.
115+
116+
For lightweight color-only support (no JS plugin required), the original [TextMate grammar](tools/textmate/) at `tools/textmate/` continues to work in IDEA Community, PyCharm CE, and VSCode.
117+
110118
## Contributing
111119

112120
This is a planned, phase-driven build under the [GSD workflow](https://github.com/anthropics/gsd) (`/gsd-execute-phase`, `/gsd-plan-phase`, etc.). Phase artifacts live in [`.planning/phases/`](.planning/phases). Read [`CLAUDE.md`](CLAUDE.md) and [`.planning/PROJECT.md`](.planning/PROJECT.md) before opening a substantive PR.

‎tools/intellij-plugin/README.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Rozie.js IntelliJ Plugin
2+
3+
> Internal dogfooding build — **Not for Marketplace distribution**.
4+
5+
Adds `.rozie` file type recognition to JetBrains IDEs with:
6+
7+
- Rozie-aware syntax highlighting (block tags, `r-*` directives, `@event.modifier(args)`, `:prop`, `{{ }}`, `$props`/`$data`/`$refs`/`$slots`/`$emit`/`$el`/`$onMount`/`$onUnmount`/`$onUpdate`/`$computed`/`$watch`)
8+
- JavaScript autocomplete + go-to-definition + rename inside `<script>` / `<props>` / `<data>` / `<listeners>` blocks (via JS language injection)
9+
- HTML / Emmet support inside `<template>` (via HTML injection); Rozie-specific attributes (`r-*`, `@event`, `:prop`, `ref`) are carved out of HTML "Unknown attribute" inspections
10+
- CSS / SCSS / Less support inside `<style>` (via CSS injection; auto-detected from `<style lang="...">`)
11+
12+
## Supported IDEs
13+
14+
Requires the bundled JavaScript plugin, so works on:
15+
16+
- **IDEA Ultimate** 2024.2+
17+
- **WebStorm** 2024.2+
18+
- **PhpStorm** 2024.2+
19+
- **RubyMine** 2024.2+
20+
- **GoLand** 2024.2+
21+
- **PyCharm Pro** 2024.2+
22+
23+
Does **not** work on IDEA Community / PyCharm Community (they don't bundle the JS plugin → language injection is a no-op). Use the [TextMate grammar](../textmate/) at `tools/textmate/` for color-only support on those IDEs.
24+
25+
## Install
26+
27+
1. Download the latest `.zip` from [GitHub Releases](../../releases?q=intellij-plugin) (look for tags starting with `intellij-plugin/v`).
28+
2. In your IDE: **Settings → Plugins → ⚙ → Install Plugin from Disk** → select the downloaded `.zip`.
29+
3. Restart the IDE.
30+
4. Open any `.rozie` file (e.g., `examples/Counter.rozie`) — block tags, directives, and magic identifiers should be highlighted; type `cons` inside `<script>` and JS autocomplete should fire.
31+
32+
**Tip:** the plugin's color settings are themable. Go to **Settings → Editor → Color Scheme → Rozie** to customize each Rozie token class independently.
33+
34+
## Dev Loop
35+
36+
Working on the plugin? Set up locally:
37+
38+
```bash
39+
cd tools/intellij-plugin
40+
41+
# Run the plugin in a sandboxed IDE instance for live testing
42+
./gradlew runIde
43+
44+
# Run the unit tests (lexer fixtures + injection smoke tests + TM↔JFlex parity + highlighter regression)
45+
./gradlew test
46+
47+
# Validate plugin.xml + check structural manifest concerns
48+
./gradlew verifyPluginStructure
49+
50+
# Comprehensive cross-version binary-compatibility check (slow, runs in CI)
51+
./gradlew verifyPlugin
52+
53+
# Build the distributable .zip
54+
./gradlew buildPlugin
55+
# Output: build/distributions/Rozie.js-0.1.0.zip
56+
57+
# Regenerate the JFlex-driven lexer (after editing src/main/jflex/Rozie.flex)
58+
./gradlew generateRozieLexer
59+
# IMPORTANT: commit the regenerated src/main/gen/_RozieLexer.java —
60+
# CI has a no-diff guard that fails if the committed file is out of sync.
61+
```
62+
63+
**Prerequisites for local dev:** JDK 21 (Temurin or Zulu) on PATH. The Gradle wrapper handles everything else (Gradle 9.5, IntelliJ Platform Gradle Plugin 2.16, IDEA Ultimate 2024.2.5 SDK).
64+
65+
## v1 Limitations
66+
67+
These are intentional v1 deferrals — captured here so dogfood users don't trip over them and file dupe issues:
68+
69+
- **`<style lang="scss">` / `<style lang="less">` is editor-only in v1 (per [D-11](../../.planning/phases/08-intellij-platform-plugin-v1-internal-dogfooding/08-CONTEXT.md)).** The plugin will syntax-highlight SCSS/Less correctly inside `<style lang="scss">` (via the bundled SCSS/Less plugin), and authoring works fine in the IDE — but the **`.rozie` compiler does NOT yet parse SCSS/Less**. The `lang` attribute is currently treated as an editor hint only; the compiler still hands the body to PostCSS as plain CSS, and SCSS-specific syntax (variables, nesting beyond CSS-nesting-spec, mixins) will fail to compile to JS targets. Authoring SCSS in `.rozie` files is therefore not a recommended workflow until v2 ships compiler-side `<style lang>` parsing. See [`.planning/todos/pending/style-lang-compiler-followup.md`](../../.planning/todos/pending/style-lang-compiler-followup.md) for the v2 backlog item.
70+
- **Mustache `{{ }}` interpolation is not JS-injected in v1** — autocomplete/go-to-def inside `{{ … }}` won't fire (per D-09 deferral; revisit if dogfood reveals demand).
71+
- **No cross-block reference resolution.** `$props.foo` in `<template>` does NOT navigate back to the `<props>` declaration (v2; depends on a custom reference contributor).
72+
- **No compiler-driven diagnostics.** Errors from `@rozie/core` (e.g., reading a non-`model: true` `$props` field) will not surface in the IDE; you'll see them at compile time only (v2 milestone).
73+
- **IDEA Community / PyCharm CE are unsupported.** They don't bundle the JS plugin, so language injection is a no-op. Use the [TextMate grammar](../textmate/) for color-only support on those IDEs.
74+
75+
## Architecture
76+
77+
See [`.planning/notes/intellij-plugin-architecture.md`](../../.planning/notes/intellij-plugin-architecture.md) for the load-bearing v1 decisions:
78+
79+
- **Thin host + language injection** (not full PSI / no LSP)
80+
- Built on the **Astro IntelliJ plugin pattern**, not Vue's (which is LSP-routed and several orders of magnitude larger)
81+
- **Out of v1 scope**: cross-block reference resolution, compiler-driven diagnostics, refactoring across blocks, Marketplace listing — all v2 milestones
82+
83+
The plugin is a single Kotlin/Gradle subproject at `tools/intellij-plugin/`, intentionally isolated from the main pnpm/Turborepo task graph (no JVM bleed into the JS workflow). It ships a JFlex-generated lexer (`_RozieLexer.java`) that emits 41 distinct `IElementType` values, a `MultiHostInjector` that hands block bodies to bundled JS / HTML / CSS plugins, an `XmlSuppressionProvider` that carves Rozie attribute names out of HTML inspections, and a `ColorSettingsPage` exposing 15 user-themable token slots.
84+
85+
## Filing Dogfood Feedback
86+
87+
Found a bug or paper-cut while authoring `.rozie` files? Open an issue with the `intellij-plugin` label:
88+
89+
1. **Repro:** the smallest `.rozie` snippet that triggers the issue
90+
2. **Expected:** what should happen (e.g., "$props.value should autocomplete")
91+
3. **Actual:** what happens instead (e.g., "no completion offered")
92+
4. **IDE + version:** e.g., "WebStorm 2024.2.5 on macOS 14.5"
93+
5. **Plugin version:** Settings → Plugins → installed plugins → "Rozie.js"
94+
95+
The dogfood goal is observation — pile up signals, fix the worst stuff in v0.2/v0.3 patch releases, decide LSP/cross-block-resolution priority for v2 based on actual pain.
96+
97+
## Versioning
98+
99+
Tags are scope-prefixed: `intellij-plugin/v0.1.0`, `intellij-plugin/v0.2.0`, etc. (per [D-04](../../.planning/phases/08-intellij-platform-plugin-v1-internal-dogfooding/08-CONTEXT.md)) so they don't collide with `@rozie/*` npm package tags.
100+
101+
Current: **v0.1.0** — initial internal dogfooding release.
102+
103+
## Stable API
104+
105+
These are user-visible surface elements that future versions WILL NOT rename:
106+
107+
- **Plugin id:** `js.rozie` (renaming would orphan every existing user's installed plugin record)
108+
- **Color scheme keys:** `ROZIE_BLOCK_TAG`, `ROZIE_R_DIRECTIVE`, `ROZIE_EVENT_AT`, `ROZIE_EVENT_NAME`, `ROZIE_MODIFIER`, `ROZIE_MODIFIER_PUNCTUATION`, `ROZIE_PROP_BINDING_PUNCT`, `ROZIE_PROP_BINDING_NAME`, `ROZIE_INTERPOLATION_DELIM`, `ROZIE_MAGIC_IDENT`, `ROZIE_REF_ATTR`, `ROZIE_LANG_ATTR`, `ROZIE_HTML_ATTR_NAME`, `ROZIE_HTML_COMMENT`, `ROZIE_BAD_CHARACTER` (renaming any of these would silently break users' saved color customizations).

0 commit comments

Comments
 (0)