build working and manual and automated tests pass!

Author: philmillman

packages/intellij-plugin/CONTEXT.md

@@ -0,0 +1,42 @@
+# Compressed context — Env Spec IntelliJ plugin
+
+## Purpose
+JetBrains plugin for [@env-spec](https://varlock.dev/env-spec) on `.env` / `.env.*`: completion, diagnostics, hover, comments, syntax, tests, CI. Parallels the [VS Code extension](../../vscode-plugin).
+
+## Build / toolchain
+- **Gradle** 9.0+ (wrapper in repo); **IntelliJ Platform Gradle Plugin** 2.13.x requires Gradle ≥ 9.0.
+- **JDK 17** for `./gradlew` (e.g. `JAVA_HOME=/opt/homebrew/opt/openjdk@17`). Java 25 + older Gradle showed a useless `What went wrong: 25` message.
+- **Plugin ZIP**: `./gradlew buildPlugin` (or `./gradlew build` — `build` depends on `buildPlugin` in `build.gradle.kts`). Output: `build/distributions/*.zip`.
+- **`./gradlew runIde`**: launches a sandbox IDE with the plugin for manual testing and opens the monorepo root (`../..` from `packages/intellij-plugin`) automatically.
+
+## UX / editor (recent)
+- **Syntax (comments/decorators)**: Comment lines now tokenize decorators with structure (`@name`, `=`, function name, arg keys/values, commas/parens) instead of a single flat comment token. New token families include `DECORATOR`, `DECORATOR_VALUE`, `DECORATOR_ARG_KEY`, and `DECORATOR_ARG_VALUE`.
+- **Syntax (assignment values)**: Assignment values now tokenize resolver function names (`if`, `eq`, etc.) and refs (`$ENV`, `${ENV}`) separately from generic value text, improving parity with VS Code highlighting.
+- **Incremental lexing stability**: Lexer now re-tokenizes from true line start (then trims to current offset), preventing state drift where highlights looked correct initially but degraded after incremental rehighlight.
+- **Color scheme page**: Added descriptors for decorator subparts, value function calls, and value references in **Settings → Editor → Color Scheme → Env Spec**.
+- **Icon**: `src/main/resources/icons/env-spec.svg`; `EnvSpecFileType.getIcon()` via `IconLoader`.
+- **Enter on `#` lines**: `EnvSpecCommentEnterHandler` (`EnterHandlerDelegate`) inserts newline + indent + `# `; registered in `plugin.xml` as `enterHandlerDelegate`.
+- **Completion insertion behavior**:
+  - Fixed duplicate/append issues on accept (Tab/Enter) by replacing `startOffset..tailOffset` instead of static line ranges.
+  - Prevents duplicate `@` when accepting decorator suggestions after typing `@`.
+  - Type-option completions now insert `optionName=` and place caret directly after `=`.
+  - Added snippet normalization for catalog insert text so VS Code-style placeholders are not inserted literally.
+
+## Tests (recent additions)
+- Added `EnvSpecLexerTest` coverage for:
+  - Decorator segmentation (`@type=enum(...)`, `@generateTypes(...)`)
+  - Arg key/value tokenization across multi-arg decorators
+  - Incomplete vs closed paren forms
+  - Mid-line incremental lexing start offsets
+  - Assignment value function/reference tokenization (`if(eq($ENV,...))`)
+- Added `EnvSpecCompletionContributorTest` coverage for:
+  - Completion match contexts immediately after `=`
+  - Snippet text normalization paths
+
+## Key paths
+| Area        | Path |
+|------------|------|
+| Plugin src | `src/main/kotlin/dev/dmno/envspec/` |
+| Plugin XML | `src/main/resources/META-INF/plugin.xml` |
+| Build      | `build.gradle.kts`, `gradle/wrapper/` |
+| Docs       | `README.md` (this file is additive only) |

packages/intellij-plugin/README.md

@@ -22,10 +22,16 @@ Inspired by the [VS Code / Open VSX extension](../../vscode-plugin):
 
 - **Documentation** on hover for decorators
 
-- **Syntax highlighting** for .env and .env.* files
+- **Syntax highlighting** for .env and .env.* files:
+  - Comment lines (`# …`) vs assignments (`KEY=value`, optional `export`)
+  - Colors follow **Settings → Editor → Color Scheme → Env Spec** (defaults match line comments, keywords, keys, `=`, and string-like values)
+
+- **Project view icon** for registered `.env` / `.env.*` files
 
 - **Toggle line comment** (`# `) support
 
+- **Enter on a `#` line** inserts a new line with the same indent and `# ` (block comment continuation)
+
 ## Installation
 
 ### From JetBrains Marketplace
@@ -48,7 +54,7 @@ Inspired by the [VS Code / Open VSX extension](../../vscode-plugin):
 ## Requirements
 
 - IntelliJ IDEA 2024.3+ or WebStorm 2024.3+
-- **Java 17** (for building) — Java 24/25 are not yet supported by Gradle 8.x and the IntelliJ Platform plugin
+- **Java 17** (for building) — use a supported JDK for the Gradle version in this repo (see Troubleshooting if you see a cryptic `25` error with Java 25)
 
 ## Development
 

packages/intellij-plugin/build.gradle.kts

@@ -27,6 +27,12 @@ tasks.test {
     useJUnitPlatform()
 }
 
+tasks.named<JavaExec>("runIde") {
+    // Open the varlock repository root when the sandbox IDE starts.
+    val repoRoot = layout.projectDirectory.dir("../..").asFile.absolutePath
+    args(repoRoot)
+}
+
 // Ensure `build` produces the plugin zip (buildPlugin is not included by default)
 tasks.named("build") {
     dependsOn(tasks.named("buildPlugin"))

packages/intellij-plugin/src/main/kotlin/dev/dmno/envspec/EnvSpecColorSettingsPage.kt

@@ -0,0 +1,57 @@
+package dev.dmno.envspec
+
+import com.intellij.openapi.editor.colors.TextAttributesKey
+import com.intellij.openapi.fileTypes.SyntaxHighlighter
+import com.intellij.openapi.options.colors.AttributesDescriptor
+import com.intellij.openapi.options.colors.ColorDescriptor
+import com.intellij.openapi.options.colors.ColorSettingsPage
+import javax.swing.Icon
+
+/**
+ * Exposes Env Spec syntax colors in Settings → Editor → Color Scheme → Env Spec.
+ */
+class EnvSpecColorSettingsPage : ColorSettingsPage {
+
+    override fun getDisplayName(): String = "Env Spec"
+
+    override fun getIcon(): Icon? = EnvSpecFileType.INSTANCE.getIcon()
+
+    override fun getHighlighter(): SyntaxHighlighter = EnvSpecSyntaxHighlighter()
+
+    override fun getDemoText(): String = """
+        # Root / header decorators
+        # @defaultRequired=false
+        # ---
+
+        # Item block
+        # @required
+        # @type=number
+        MY_URL="test.com"
+        export PUBLIC_API=https://api.example.com
+
+    """.trimIndent()
+
+    override fun getAdditionalHighlightingTagToDescriptorMap(): Map<String, TextAttributesKey>? = null
+
+    override fun getAttributeDescriptors(): Array<AttributesDescriptor> = DESCRIPTORS
+
+    override fun getColorDescriptors(): Array<ColorDescriptor> = ColorDescriptor.EMPTY_ARRAY
+
+    companion object {
+        private val DESCRIPTORS = arrayOf(
+            AttributesDescriptor("Comment", EnvSpecSyntaxHighlighter.LINE_COMMENT),
+            AttributesDescriptor("Decorator", EnvSpecSyntaxHighlighter.DECORATOR),
+            AttributesDescriptor("Decorator value", EnvSpecSyntaxHighlighter.DECORATOR_VALUE),
+            AttributesDescriptor("Decorator function args", EnvSpecSyntaxHighlighter.DECORATOR_ARGS),
+            AttributesDescriptor("Decorator arg key", EnvSpecSyntaxHighlighter.DECORATOR_ARG_KEY),
+            AttributesDescriptor("Decorator arg value", EnvSpecSyntaxHighlighter.DECORATOR_ARG_VALUE),
+            AttributesDescriptor("Export keyword", EnvSpecSyntaxHighlighter.EXPORT_KEYWORD),
+            AttributesDescriptor("Variable name", EnvSpecSyntaxHighlighter.ENV_KEY),
+            AttributesDescriptor("Assignment (=)", EnvSpecSyntaxHighlighter.EQUALS),
+            AttributesDescriptor("Value", EnvSpecSyntaxHighlighter.ENV_VALUE),
+            AttributesDescriptor("Value function call", EnvSpecSyntaxHighlighter.VALUE_FUNCTION),
+            AttributesDescriptor("Value item reference", EnvSpecSyntaxHighlighter.VALUE_REFERENCE),
+            AttributesDescriptor("Other text", EnvSpecSyntaxHighlighter.DEFAULT),
+        )
+    }
+}

packages/intellij-plugin/src/main/kotlin/dev/dmno/envspec/EnvSpecCommentEnterHandler.kt

@@ -0,0 +1,60 @@
+package dev.dmno.envspec
+
+import com.intellij.codeInsight.editorActions.enter.EnterHandlerDelegate
+import com.intellij.openapi.actionSystem.DataContext
+import com.intellij.openapi.command.WriteCommandAction
+import com.intellij.openapi.editor.Editor
+import com.intellij.openapi.editor.actionSystem.EditorActionHandler
+import com.intellij.openapi.util.Ref
+import com.intellij.psi.PsiFile
+
+/**
+ * After Enter on a line that starts (after whitespace) with `#`, inserts a new line and `# `
+ * with the same leading indentation — same idea as VS Code onEnterRules for line comments.
+ */
+class EnvSpecCommentEnterHandler : EnterHandlerDelegate {
+
+    override fun preprocessEnter(
+        file: PsiFile,
+        editor: Editor,
+        caretOffsetRef: Ref<Int>,
+        caretAdvance: Ref<Int>,
+        dataContext: DataContext,
+        originalHandler: EditorActionHandler?,
+    ): EnterHandlerDelegate.Result {
+        if (file.language != EnvSpecLanguage) return EnterHandlerDelegate.Result.Continue
+
+        val document = editor.document
+        val caretOffset = caretOffsetRef.get()
+        val line = document.getLineNumber(caretOffset)
+        val lineStart = document.getLineStartOffset(line)
+        val lineEnd = document.getLineEndOffset(line)
+        val lineText = document.charsSequence.subSequence(lineStart, lineEnd).toString()
+
+        val m = COMMENT_LINE_PREFIX.matchEntire(lineText) ?: return EnterHandlerDelegate.Result.Continue
+        val indent = m.groupValues[1]
+        val hashOffset = lineStart + indent.length
+        if (caretOffset < hashOffset) return EnterHandlerDelegate.Result.Continue
+
+        val project = file.project
+        val insert = "\n$indent# "
+        WriteCommandAction.runWriteCommandAction(project) {
+            document.insertString(caretOffset, insert)
+            val newOffset = caretOffset + insert.length
+            caretOffsetRef.set(newOffset)
+            caretAdvance.set(0)
+            editor.caretModel.moveToOffset(newOffset)
+        }
+        return EnterHandlerDelegate.Result.Stop
+    }
+
+    override fun postProcessEnter(
+        file: PsiFile,
+        editor: Editor,
+        dataContext: DataContext,
+    ): EnterHandlerDelegate.Result = EnterHandlerDelegate.Result.Continue
+
+    companion object {
+        private val COMMENT_LINE_PREFIX = Regex("""^([ \t]*)(#.*)$""")
+    }
+}

packages/intellij-plugin/src/main/kotlin/dev/dmno/envspec/EnvSpecCompletionContributor.kt

@@ -27,6 +27,11 @@ class EnvSpecCompletionContributor : CompletionContributor() {
 
     companion object {
         private val ENV_KEY_PATTERN = Pattern.compile("^\\s*([A-Za-z_][A-Za-z0-9_]*)\\s*=")
+        private val KOTLIN_ESCAPED_DOLLAR_RE = Regex("\\$\\{'\\$'\\}")
+        private val CHOICE_SNIPPET_RE = Regex("""\$\{\d+\|([^}]*)\|\}""")
+        private val DEFAULT_SNIPPET_RE = Regex("""\$\{\d+:([^}]*)\}""")
+        private val TABSTOP_SNIPPET_RE = Regex("""\$\{\d+\}""")
+        private val SIMPLE_TABSTOP_SNIPPET_RE = Regex("""\$\d+""")
     }
 
     private fun doAddCompletions(params: CompletionParameters, result: CompletionResultSet) {
@@ -104,6 +109,10 @@ class EnvSpecCompletionContributor : CompletionContributor() {
 
     private data class ReplaceRange(val line: Int, val start: Int, val end: Int)
 
+    override fun invokeAutoPopup(position: com.intellij.psi.PsiElement, typeChar: Char): Boolean {
+        return typeChar == '@' || typeChar == '$' || typeChar == '=' || typeChar == ','
+    }
+
     private fun matchDecoratorName(commentPrefix: String, line: Int, offset: Int, lineStart: Int): ReplaceRange? {
         val match = Regex("(^|\\s)(@[\\w-]*)$").find(commentPrefix) ?: return null
         val token = match.groupValues[2]
@@ -136,13 +145,13 @@ class EnvSpecCompletionContributor : CompletionContributor() {
     }
 
     private fun matchResolverValue(linePrefix: String, line: Int, offset: Int, lineStart: Int): ReplaceRange? {
-        val match = Regex("(?:=\\s*|[(,]\\s*)([A-Za-z][\\w-]*)$").find(linePrefix) ?: return null
+        val match = Regex("(?:=\\s*|[(,]\\s*)([A-Za-z]?[\\w-]*)$").find(linePrefix) ?: return null
         val endInLine = offset - lineStart
         return ReplaceRange(line, endInLine - match.groupValues[1].length, endInLine)
     }
 
     private fun matchDecoratorValue(commentPrefix: String, line: Int, offset: Int, lineStart: Int): ReplaceRangeDecorator? {
-        val match = Regex("(^|\\s)@([\\w-]+)=([A-Za-z][\\w-]*)$").find(commentPrefix) ?: return null
+        val match = Regex("(^|\\s)@([\\w-]+)=([A-Za-z]?[\\w-]*)$").find(commentPrefix) ?: return null
         val decorator = EnvSpecCatalog.DECORATORS_BY_NAME[match.groupValues[2]]
         val typedValue = match.groupValues[3]
         val endInLine = offset - lineStart
@@ -167,7 +176,7 @@ class EnvSpecCompletionContributor : CompletionContributor() {
     private data class EnumValueContext(val range: ReplaceRange, val enumValues: List<String>)
 
     private fun createDecoratorItem(info: DecoratorInfo, range: ReplaceRange): LookupElementBuilder {
-        val insertHandler = createReplaceHandler(range, info.insertText)
+        val insertHandler = createReplaceHandler(info.insertText)
         var item = LookupElementBuilder.create("@${info.name}")
             .withInsertHandler(insertHandler)
             .withTypeText(if (info.scope == "root") "Root decorator" else "Item decorator")
@@ -178,36 +187,66 @@ class EnvSpecCompletionContributor : CompletionContributor() {
         return item
     }
 
-    private fun createReplaceHandler(range: ReplaceRange, insertText: String): InsertHandler<LookupElement> {
+    private fun createReplaceHandler(insertText: String, caretOffsetInInsert: Int? = null): InsertHandler<LookupElement> {
+        val normalizedInsertText = normalizeSnippetInsertText(insertText)
         return InsertHandler { ctx: InsertionContext, _ ->
             WriteCommandAction.runWriteCommandAction(ctx.project) {
                 val doc = ctx.document
-                val start = doc.getLineStartOffset(range.line) + range.start
-                val end = doc.getLineStartOffset(range.line) + range.end
-                doc.replaceString(start, end, insertText)
+                // IntelliJ applies default completion insertion before this handler runs.
+                // Replace that inserted segment directly to avoid duplicate/append behavior.
+                val start = ctx.startOffset
+                val end = ctx.tailOffset
+                val hasAtPrefix = start > 0 && doc.charsSequence[start - 1] == '@'
+                val textToInsert = if (hasAtPrefix && normalizedInsertText.startsWith("@")) {
+                    normalizedInsertText.substring(1)
+                } else {
+                    normalizedInsertText
+                }
+                ctx.setAddCompletionChar(false)
+                doc.replaceString(start, end, textToInsert)
+                ctx.tailOffset = start + textToInsert.length
+                val caretOffset = if (caretOffsetInInsert == null) {
+                    start + textToInsert.length
+                } else {
+                    start + caretOffsetInInsert.coerceIn(0, textToInsert.length)
+                }
+                ctx.editor.caretModel.moveToOffset(caretOffset)
             }
         }
     }
 
+    private fun normalizeSnippetInsertText(text: String): String {
+        var out = text
+        out = KOTLIN_ESCAPED_DOLLAR_RE.replace(out) { "$" }
+        out = CHOICE_SNIPPET_RE.replace(out) { match ->
+            match.groupValues[1].split(",").firstOrNull()?.trim().orEmpty()
+        }
+        out = DEFAULT_SNIPPET_RE.replace(out) { match -> match.groupValues[1] }
+        out = TABSTOP_SNIPPET_RE.replace(out, "")
+        out = SIMPLE_TABSTOP_SNIPPET_RE.replace(out, "")
+        return out
+    }
+
     private fun createDataTypeItem(info: DataTypeInfo, range: ReplaceRange): LookupElementBuilder {
         val insertText = info.insertText ?: info.name
         return LookupElementBuilder.create(info.name)
-            .withInsertHandler(createReplaceHandler(range, insertText))
+            .withInsertHandler(createReplaceHandler(insertText))
             .withTypeText("@type data type")
             .withTailText(" ${info.summary}", true)
     }
 
     private fun createDataTypeOptionItem(option: DataTypeOptionSnippet, context: ReplaceRangeData): LookupElementBuilder {
         val range = context.range
+        val insertText = "${option.name}="
         return LookupElementBuilder.create(option.name)
-            .withInsertHandler(createReplaceHandler(range, option.insertText))
+            .withInsertHandler(createReplaceHandler(insertText, insertText.length))
             .withTypeText("@type option")
             .withTailText(" ${option.documentation}", true)
     }
 
     private fun createResolverItem(info: ResolverInfo, range: ReplaceRange): LookupElementBuilder {
         return LookupElementBuilder.create("${info.name}()")
-            .withInsertHandler(createReplaceHandler(range, info.insertText))
+            .withInsertHandler(createReplaceHandler(info.insertText))
             .withTypeText("Resolver function")
             .withTailText(" ${info.summary}", true)
     }
@@ -220,7 +259,7 @@ class EnvSpecCompletionContributor : CompletionContributor() {
         }
         return keys.sorted().map { key ->
             LookupElementBuilder.create(key)
-                .withInsertHandler(createReplaceHandler(range, key))
+                .withInsertHandler(createReplaceHandler(key))
                 .withTypeText("Config item reference")
                 .withTailText(" Reference `$key` with `\$$key`.", true)
         }
@@ -229,7 +268,7 @@ class EnvSpecCompletionContributor : CompletionContributor() {
     private fun createKeywordItems(values: List<String>, range: ReplaceRange): List<LookupElementBuilder> {
         return values.map { value ->
             LookupElementBuilder.create(value)
-                .withInsertHandler(createReplaceHandler(range, value))
+                .withInsertHandler(createReplaceHandler(value))
         }
     }
 
@@ -249,7 +288,7 @@ class EnvSpecCompletionContributor : CompletionContributor() {
         val range = context.range
         return context.enumValues.map { value ->
             LookupElementBuilder.create(value)
-                .withInsertHandler(createReplaceHandler(range, value))
+                .withInsertHandler(createReplaceHandler(value))
                 .withTypeText("@type=enum value")
                 .withTailText(" Allowed enum value `$value`.", true)
         }

packages/intellij-plugin/src/main/kotlin/dev/dmno/envspec/EnvSpecFileType.kt

@@ -1,17 +1,20 @@
 package dev.dmno.envspec
 
-import com.intellij.lang.Language
 import com.intellij.openapi.fileTypes.LanguageFileType
+import com.intellij.openapi.util.IconLoader
 import javax.swing.Icon
 
 class EnvSpecFileType private constructor() : LanguageFileType(EnvSpecLanguage) {
 
     override fun getName(): String = "EnvSpec"
     override fun getDescription(): String = "@env-spec (.env) file"
     override fun getDefaultExtension(): String = "env"
-    override fun getIcon(): Icon? = null
+    override fun getIcon(): Icon = ICON
 
     companion object {
+        @JvmField
+        val ICON: Icon = IconLoader.getIcon("/icons/env-spec.svg", EnvSpecFileType::class.java)
+
         @JvmStatic
         val INSTANCE = EnvSpecFileType()
     }