JetBrains IDE Plugin

The dev.kuml.intellij plugin adds editor support for kUML script files in every JetBrains IDE based on IntelliJ Platform build 243+ (IDEA 2024.3 or newer). It is intentionally minimal — Syntax highlighting, default imports, file icon. Nothing more, nothing less.

Install

Settings → Plugins → Marketplace, search for kUML, click Install, restart the IDE.

Or install a local .zip distribution built from source:

./gradlew :kuml-jetbrains:kuml-jetbrains-plugin:buildPlugin
# → kuml-jetbrains/kuml-jetbrains-plugin/build/distributions/kuml-jetbrains-plugin-X.Y.Z.zip

Then Settings → Plugins → ⚙ → Install Plugin from Disk… and pick the zip.

What you get

  • Syntax highlighting — full Kotlin highlighting inherited from the bundled Kotlin plugin. kUML DSL builders (classDiagram, umlModel, classOf, c4Model, …) highlight like ordinary Kotlin functions because that’s exactly what they are.

  • Default imports resolved by the editor — when you type classDiagram(name = "X") { }, IntelliJ knows classDiagram comes from dev.kuml.core.dsl even though there’s no import line. Same for dev.kuml.uml.dsl., dev.kuml.c4.dsl., dev.kuml.core.model.*, and the UML / C4 metamodel packages.

  • Structure view — diagrams and elements show up in the Structure tool window (since they’re nested Kotlin lambdas).

  • Refactoring & Find Usages — works the same as for any Kotlin file. Rename a classifier val, every reference updates. Find Usages on classOf(…​) lists every call site.

  • Custom file icon — *.kuml.kts files are visually distinct in the project view and editor tabs.

Annotator and Quick Fixes (V2.0.28a)

The plugin highlights .kuml.kts errors inline using the same validation engine as kuml validate — no external process required. Errors and warnings appear as red/yellow wave underlines directly in the editor; hover to read the constraint name and OCL body.

Four quick-fix types are offered via the intention-action bulb (Alt+Enter):

Quick fix What it does

Add missing constraint body

Inserts a placeholder OCL expression self.todo = true inside an empty constraint(name, body = …​) call so the file compiles.

Remove duplicate element

Deletes the duplicate classOf / interfaceOf / stereotype call that caused a duplicate-id structural violation.

Add required port direction

Inserts direction = PortDirection.In (or .Out) on a port(…​) call that is missing the direction argument.

Break circular inheritance

Removes the generalization(child = …​, parent = …​) edge that closes a cycle.

Quick fixes are applied in-editor, with full undo history. The annotator re-evaluates on every keystroke (debounced at 300 ms) so the underlines clear as soon as the violation is resolved.

The annotator runs the kUML structural checker synchronously in the IDE’s background thread pool. For scripts with many elements, the first annotation pass may take 1–2 seconds on a cold editor open. Subsequent passes are sub-100 ms because the compiled model is cached by the IDE’s Kotlin scripting host.

Live SVG Preview (V2.0.28b / V2.0.30)

Opening any .kuml.kts file activates a split editor: the source is on the left, a live SVG preview panel on the right. The preview updates automatically — changes in the source trigger a re-render after a 300 ms debounce, so the SVG stays in sync without blocking the typing flow.

The preview toolbar provides:

  • Zoom in / Zoom out — incrementally scale the SVG (shortcut: Cmd+= / Cmd+–).

  • Fit to panel — reset zoom so the entire diagram is visible.

  • Pan mode — toggle hand-drag panning (click and drag the SVG canvas).

  • Refresh — force a re-render even if the file has not changed on disk.

  • Copy SVG — copy the current SVG source to the clipboard.

  • Open in browser — save a temporary file and open the system browser for full-resolution inspection.

The live preview is rendered by the same kUML rendering engine as kuml render — the SVG is byte-identical to the CLI output for the same theme and engine settings. Theme and layout engine are read from kuml.config.kts in the project root if present.

If the SVG preview panel is not visible after opening a .kuml.kts file, toggle it via View → Tool Windows → kUML Preview, or split the editor manually with the preview button in the gutter (the kUML file-type icon on the right edge of the editor).

Structure View (V2.0.28b)

The IntelliJ Structure tool window (Alt+7) shows the diagram element tree for any open .kuml.kts file. The tree mirrors the DSL nesting:

  • Diagram node (e.g. classDiagram "Domain")

    • Classifiers (classes, interfaces, enums)

      • Attributes and operations

    • Relationships (generalisations, associations, realisations)

Clicking any tree node navigates the cursor to the corresponding DSL call in the source. The tree updates in sync with the live preview — the same 300 ms debounce applies.

The Structure view is particularly useful for large scripts with many elements: use Ctrl+F (or the search field in the tool window header) to filter the tree by element name.

The Structure view is provided by kUML’s own StructureViewBuilder extension, not by IntelliJ’s default Kotlin structure provider. It shows kUML model semantics (classifiers, ports, state machines) rather than raw Kotlin symbols.

Under the hood

The plugin registers a ScriptDefinitionsProvider (Kotlin scripting extension point) that hands the dev.kuml.core.script.KumlScript template to IntelliJ’s Kotlin plugin. The Kotlin plugin reads the @KotlinScript(fileExtension = "kuml.kts", …) annotation and provides the editing experience.

There is no custom lexer, no custom parser, no custom annotator — we ride entirely on the Kotlin plugin’s investment. That keeps the plugin tiny (12 KB distribution + bundled runtime JARs) and inherits every future improvement to Kotlin scripting for free.

The bundled runtime includes:

  • kuml-core-script — the script template

  • kuml-core-model, kuml-core-dsl — DSL surface for resolution

  • kuml-metamodel-uml, kuml-metamodel-c4 — metamodel types

  • The Kotlin scripting infrastructure

So default imports resolve to real symbols in the editor — autocomplete works, hover shows KDoc, Go to Declaration opens the metamodel class.

What’s deliberately NOT in scope

  • Language Server Protocol — pure platform-plugin implementation, no LSP layer. Not planned until there is user demand from non-JetBrains editors.

  • Refactoring helpers beyond Kotlin — no "Extract package", no "Rename diagram", no "Convert class to interface". Kotlin’s general-purpose refactoring still works.

Features that were originally listed as V2 aspirations and have since shipped:

  • Inline annotator + quick fixes — shipped in V2.0.28a (see above).

  • Live SVG preview panel — shipped in V2.0.28b / V2.0.30 (see above).

  • Structure view — shipped in V2.0.28b (see above).

Configuration

None. The plugin has no settings panel because there’s nothing to configure. If you want to choose a theme, generator, or layout engine, do that in kuml.config.kts or on the command line — the IDE plugin is for editing, not for rendering.

Troubleshooting

Symptom Likely cause

Editor highlights classDiagram as unresolved

The kUML plugin isn’t enabled, or the Kotlin plugin is disabled. Check Settings → Plugins → Installed.

File opens as plain text, no syntax highlighting

The file extension isn’t .kuml.kts. The plugin only activates on that suffix.

Refactoring renames break references in other *.kuml.kts files

The Kotlin scripting infrastructure indexes scripts independently. Run Invalidate Caches and Restart after large refactors.

Performance degrades with many *.kuml.kts files

Each script is independently compiled by the IDE’s Kotlin plugin. Performance scales with script count and complexity; if you have hundreds of scripts, consider splitting the project so the IDE only indexes the subset you’re editing.