feat: underline grammar-engine-backed keys behind a dedicated flag (#467)

A debug aid for the grammar engine work: while enabled, underline the KEY
of every option whose value is backed by a GrammarOptionValue, so it's
obvious at a glance which keys the new engine covers. The key keeps its
normal color and just gets a gray underline — recoloring grammar vs
non-grammar keys was too distracting, especially on light themes.

Gated on its own experimental flag (underlineGrammarEngineKeys, off by
default), independent of useGrammarParseEngine: the grammar validators
exist in the registry regardless of which validation path is active, so
this toggles on its own. Surfaced as a third checkbox on the settings page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Steve Ramage

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/annotators/GrammarEngineKeyAnnotator.kt

@@ -0,0 +1,55 @@
+package net.sjrx.intellij.plugins.systemdunitfiles.annotators
+
+import com.intellij.lang.annotation.AnnotationHolder
+import com.intellij.lang.annotation.Annotator
+import com.intellij.lang.annotation.HighlightSeverity
+import com.intellij.openapi.editor.colors.TextAttributesKey
+import com.intellij.openapi.editor.markup.EffectType
+import com.intellij.openapi.editor.markup.TextAttributes
+import com.intellij.psi.PsiElement
+import com.intellij.psi.util.PsiTreeUtil
+import com.intellij.ui.JBColor
+import net.sjrx.intellij.plugins.systemdunitfiles.psi.UnitFileProperty
+import net.sjrx.intellij.plugins.systemdunitfiles.psi.UnitFileSectionType
+import net.sjrx.intellij.plugins.systemdunitfiles.semanticdata.SemanticDataRepository
+import net.sjrx.intellij.plugins.systemdunitfiles.semanticdata.fileClass
+import net.sjrx.intellij.plugins.systemdunitfiles.semanticdata.optionvalues.grammar.GrammarOptionValue
+import net.sjrx.intellij.plugins.systemdunitfiles.settings.ExperimentalSettings
+import java.awt.Font
+
+/**
+ * Debug aid (#467): while the "underline grammar-engine keys" flag is enabled, underline the KEY of
+ * every option whose value is validated by a [GrammarOptionValue], so it is obvious at a glance which
+ * keys are backed by the new grammar engine versus the original SyntacticMatch/SemanticMatch path.
+ *
+ * Gated on its own flag ([ExperimentalSettings.State.underlineGrammarEngineKeys]), independent of
+ * whether the grammar engine is the active validation path — the grammar validators exist in the
+ * registry either way. Does nothing when the flag is off, so it has no effect for normal users.
+ */
+class GrammarEngineKeyAnnotator : Annotator {
+
+  override fun annotate(element: PsiElement, holder: AnnotationHolder) {
+    if (element !is UnitFileProperty) return
+    if (!ExperimentalSettings.getInstance(element.project).state.underlineGrammarEngineKeys) return
+
+    val section = PsiTreeUtil.getParentOfType(element, UnitFileSectionType::class.java) ?: return
+    val fileClass = element.containingFile.fileClass()
+    val validator = SemanticDataRepository.instance.getOptionValidator(fileClass, section.sectionName, element.key)
+
+    if (validator is GrammarOptionValue) {
+      holder.newSilentAnnotation(HighlightSeverity.INFORMATION)
+        .range(element.keyNode.psi)
+        .textAttributes(NEW_ENGINE_KEY)
+        .create()
+    }
+  }
+
+  companion object {
+    // Underline the key, keeping its normal color — recoloring grammar vs non-grammar keys with two
+    // different colors was too distracting, especially on light themes.
+    val NEW_ENGINE_KEY: TextAttributesKey = TextAttributesKey.createTextAttributesKey(
+      "SYSTEMD_UNIT_FILE_NEW_GRAMMAR_ENGINE_KEY",
+      TextAttributes(null, null, JBColor.GRAY, EffectType.LINE_UNDERSCORE, Font.PLAIN),
+    )
+  }
+}

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/settings/ExperimentalSettings.kt

@@ -24,6 +24,14 @@ class ExperimentalSettings : PersistentStateComponent<ExperimentalSettings.State
      * validation instead of the original SyntacticMatch/SemanticMatch path.
      */
     var useGrammarParseEngine: Boolean = false
+
+    /**
+     * Underline the KEY of every option whose value is backed by a grammar validator
+     * ([GrammarOptionValue]), a debug aid for seeing which keys the new engine covers. Independent of
+     * [useGrammarParseEngine]: the grammar validators exist in the registry regardless of which
+     * validation path is active, so this can be toggled on its own.
+     */
+    var underlineGrammarEngineKeys: Boolean = false
   }
 
   override fun getState(): State = myState

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/settings/PodmanQuadletConfigurable.kt

@@ -11,6 +11,7 @@ class PodmanQuadletConfigurable(private val project: Project) : Configurable {
 
   private var enabledCheckbox: JBCheckBox? = null
   private var grammarEngineCheckbox: JBCheckBox? = null
+  private var underlineGrammarKeysCheckbox: JBCheckBox? = null
 
   override fun getDisplayName(): String = "systemd Unit Files"
 
@@ -22,10 +23,15 @@ class PodmanQuadletConfigurable(private val project: Project) : Configurable {
       "Use the new grammar engine for value validation (experimental)",
       experimental.state.useGrammarParseEngine,
     )
+    underlineGrammarKeysCheckbox = JBCheckBox(
+      "Underline keys backed by the new grammar engine (experimental)",
+      experimental.state.underlineGrammarEngineKeys,
+    )
 
     return FormBuilder.createFormBuilder()
       .addComponent(enabledCheckbox!!)
       .addComponent(grammarEngineCheckbox!!)
+      .addComponent(underlineGrammarKeysCheckbox!!)
       .addComponentFillVertically(JPanel(), 0)
       .panel
   }
@@ -34,7 +40,8 @@ class PodmanQuadletConfigurable(private val project: Project) : Configurable {
     val settings = PodmanQuadletSettings.getInstance(project)
     val experimental = ExperimentalSettings.getInstance(project)
     return enabledCheckbox?.isSelected != settings.state.enabled ||
-      grammarEngineCheckbox?.isSelected != experimental.state.useGrammarParseEngine
+      grammarEngineCheckbox?.isSelected != experimental.state.useGrammarParseEngine ||
+      underlineGrammarKeysCheckbox?.isSelected != experimental.state.underlineGrammarEngineKeys
   }
 
   override fun apply() {
@@ -45,12 +52,16 @@ class PodmanQuadletConfigurable(private val project: Project) : Configurable {
     }
     settings.state.enabled = newEnabled
 
-    ExperimentalSettings.getInstance(project).state.useGrammarParseEngine = grammarEngineCheckbox?.isSelected ?: false
+    val experimental = ExperimentalSettings.getInstance(project)
+    experimental.state.useGrammarParseEngine = grammarEngineCheckbox?.isSelected ?: false
+    experimental.state.underlineGrammarEngineKeys = underlineGrammarKeysCheckbox?.isSelected ?: false
   }
 
   override fun reset() {
     val settings = PodmanQuadletSettings.getInstance(project)
+    val experimental = ExperimentalSettings.getInstance(project)
     enabledCheckbox?.isSelected = settings.state.enabled
-    grammarEngineCheckbox?.isSelected = ExperimentalSettings.getInstance(project).state.useGrammarParseEngine
+    grammarEngineCheckbox?.isSelected = experimental.state.useGrammarParseEngine
+    underlineGrammarKeysCheckbox?.isSelected = experimental.state.underlineGrammarEngineKeys
   }
 }

src/main/resources/META-INF/plugin.xml

@@ -62,6 +62,7 @@
     <annotator language="Unit File (systemd)" implementationClass="net.sjrx.intellij.plugins.systemdunitfiles.annotators.PidFileOptionWarning"/>
     <annotator language="Unit File (systemd)" implementationClass="net.sjrx.intellij.plugins.systemdunitfiles.annotators.DeprecatedGrammarValueAnnotator"/>
     <annotator language="Unit File (systemd)" implementationClass="net.sjrx.intellij.plugins.systemdunitfiles.annotators.GrammarValueColorAnnotator"/>
+    <annotator language="Unit File (systemd)" implementationClass="net.sjrx.intellij.plugins.systemdunitfiles.annotators.GrammarEngineKeyAnnotator"/>
     <localInspection implementationClass="net.sjrx.intellij.plugins.systemdunitfiles.inspections.UnknownKeyInSectionInspection"
                      groupPath="Unit files (systemd)" language="Unit File (systemd)"
                      shortName="UnknownKeyInSection"     displayName="Unknown option in section"

src/test/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/annotators/GrammarEngineKeyAnnotatorTest.kt

@@ -0,0 +1,50 @@
+package net.sjrx.intellij.plugins.systemdunitfiles.annotators
+
+import com.intellij.lang.annotation.HighlightSeverity
+import net.sjrx.intellij.plugins.systemdunitfiles.AbstractUnitFileTest
+import net.sjrx.intellij.plugins.systemdunitfiles.settings.ExperimentalSettings
+import org.junit.Test
+
+class GrammarEngineKeyAnnotatorTest : AbstractUnitFileTest() {
+
+  // The light-test project is shared across classes, so don't leak the opt-in.
+  override fun tearDown() {
+    try {
+      ExperimentalSettings.getInstance(project).state.underlineGrammarEngineKeys = false
+      ExperimentalSettings.getInstance(project).state.useGrammarParseEngine = false
+    } finally {
+      super.tearDown()
+    }
+  }
+
+  private fun markedKey(highlights: List<com.intellij.codeInsight.daemon.impl.HighlightInfo>, key: String) =
+    highlights.any { it.severity == HighlightSeverity.INFORMATION && it.text == key }
+
+  @Test
+  fun testGrammarBackedKeyIsMarkedWhenFlagOn() {
+    ExperimentalSettings.getInstance(project).state.underlineGrammarEngineKeys = true
+    // RestrictAddressFamilies is validated by a GrammarOptionValue.
+    setupFileInEditor("file.service", "[Service]\nRestrictAddressFamilies=AF_INET\n")
+
+    val highlights = myFixture.doHighlighting()
+    assertTrue(markedKey(highlights, "RestrictAddressFamilies"))
+  }
+
+  @Test
+  fun testNotMarkedWhenFlagOff() {
+    setupFileInEditor("file.service", "[Service]\nRestrictAddressFamilies=AF_INET\n")
+
+    val highlights = myFixture.doHighlighting()
+    assertFalse(markedKey(highlights, "RestrictAddressFamilies"))
+  }
+
+  @Test
+  fun testIndependentOfParseEngineFlag() {
+    // The underline flag drives this annotator on its own; turning on only the parse engine must not
+    // mark keys, and turning on only the underline flag must (proving the two flags are decoupled).
+    ExperimentalSettings.getInstance(project).state.useGrammarParseEngine = true
+    setupFileInEditor("file.service", "[Service]\nRestrictAddressFamilies=AF_INET\n")
+
+    assertFalse(markedKey(myFixture.doHighlighting(), "RestrictAddressFamilies"))
+  }
+}