feat: valid-but-deprecated grammar values behind the experimental flag (AF families + IPMasquerade booleans) (#495)

* feat: warn on valid-but-deprecated grammar values behind the experimental flag

A value can be perfectly valid yet use an obsolete token — e.g. an address
family the kernel removed but af_from_name still resolves. Add a reusable
deprecation layer:

- TerminalCombinator.deprecationFor(token): String? = null — additive hook.
- FlexibleLiteralChoiceTerminal.deprecating(map) marks choices obsolete.
- Combinator.deprecatedTokens(value) reports them from the first fully-VALID
  parse, so a deprecation note never stacks on an InvalidValue error.
- DeprecatedGrammarValueAnnotator renders them as WEAK_WARNINGs, gated behind
  ExperimentalSettings.useGrammarParseEngine (off by default, like the other
  grammar-engine features).

First user: RestrictAddressFamilies= warns on AF_DECnet / AF_IRDA / AF_ECONET /
AF_WANPIPE (kernel-removed, reasons per address_families(7)). Re-cut of stacked
PR #484 against current 242.x.

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

* feat: flag deprecated IPMasquerade= boolean values

A second user of the deprecation layer, found by scanning systemd.network(5):
the boolean forms of IPMasquerade= "are now deprecated. Please use one of the
values above" (ipv4/ipv6/both/no). The validator already enumerated the eleven
boolean aliases as accepted values; mark them deprecated so they get the weak
warning (truthy -> use "ipv4", falsy -> use "no"). Demonstrates the layer is
generic across grammars, not AF-specific.

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

---------

Co-authored-by: Steve Ramage <gitcommits@sjrx.net>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

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

@@ -0,0 +1,42 @@
+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.util.TextRange
+import com.intellij.psi.PsiElement
+import com.intellij.psi.util.PsiTreeUtil
+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.semanticdata.optionvalues.grammar.deprecatedTokens
+import net.sjrx.intellij.plugins.systemdunitfiles.settings.ExperimentalSettings
+
+/**
+ * Flags valid-but-deprecated values with a weak warning (#467), behind the experimental flag.
+ *
+ * Generic: any grammar can mark choices deprecated (see [GrammarOptionValue]'s terminals). The first
+ * user is RestrictAddressFamilies=, warning on kernel-removed families like AF_DECnet.
+ */
+class DeprecatedGrammarValueAnnotator : Annotator {
+
+  override fun annotate(element: PsiElement, holder: AnnotationHolder) {
+    if (element !is UnitFileProperty) return
+    if (!ExperimentalSettings.getInstance(element.project).state.useGrammarParseEngine) return
+
+    val section = PsiTreeUtil.getParentOfType(element, UnitFileSectionType::class.java) ?: return
+    val value = element.valueText ?: return
+    val base = element.valueNode?.psi?.textRange?.startOffset ?: return
+    val fileClass = element.containingFile.fileClass()
+    val validator = SemanticDataRepository.instance.getOptionValidator(fileClass, section.sectionName, element.key)
+    if (validator !is GrammarOptionValue) return
+
+    for (deprecated in validator.combinator.deprecatedTokens(value)) {
+      holder.newAnnotation(HighlightSeverity.WEAK_WARNING, deprecated.message)
+        .range(TextRange(base + deprecated.start, base + deprecated.end))
+        .create()
+    }
+  }
+}

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/semanticdata/optionvalues/ai/ConfigParseAddressFamiliesOptionValue.kt

@@ -98,6 +98,15 @@ class ConfigParseAddressFamiliesOptionValue : SimpleGrammarOptionValues(
             "AF_WANPIPE",
             "AF_X25",
             "AF_XDP"
+        ).deprecating(
+            // Still resolved by af_from_name (the libc macro exists) but the kernel removed the
+            // protocol, so configuring them has no effect. Reasons per address_families(7).
+            mapOf(
+                "AF_DECnet" to "AF_DECnet is obsolete: DECnet support was removed from the Linux kernel in 6.1.",
+                "AF_IRDA" to "AF_IRDA is obsolete: IrDA support was removed from the Linux kernel in 4.17.",
+                "AF_ECONET" to "AF_ECONET is obsolete: Acorn Econet support was removed from the Linux kernel in 3.5.",
+                "AF_WANPIPE" to "AF_WANPIPE is obsolete: WANPIPE support was removed from the Linux kernel in 2.6.21.",
+            )
         )
     }
 }

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/semanticdata/optionvalues/ai/ConfigParseIpMasqueradeOptionValue.kt

@@ -22,6 +22,17 @@ class ConfigParseIpMasqueradeOptionValue : SimpleGrammarOptionValues(
             "1", "yes", "y", "true", "t", "on",
             // Deprecated boolean false values (map to no)
             "0", "n", "false", "f", "off"
+        ).deprecating(
+            // systemd.network(5): the boolean forms "are now deprecated. Please use one of the
+            // values above" (ipv4/ipv6/both/no). Still accepted; the truthy forms map to ipv4.
+            buildMap {
+                for (t in listOf("1", "yes", "y", "true", "t", "on")) {
+                    put(t, "Boolean values for IPMasquerade= are deprecated; use \"ipv4\" (or \"ipv6\"/\"both\") instead.")
+                }
+                for (f in listOf("0", "n", "false", "f", "off")) {
+                    put(f, "Boolean values for IPMasquerade= are deprecated; use \"no\" instead.")
+                }
+            }
         ),
         EOF()
     )

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/semanticdata/optionvalues/grammar/Deprecations.kt

@@ -0,0 +1,23 @@
+package net.sjrx.intellij.plugins.systemdunitfiles.semanticdata.optionvalues.grammar
+
+/*
+ * Valid-but-deprecated value detection (#467). A reusable companion to validation: a value can be
+ * perfectly valid yet use an obsolete token (e.g. an address family the kernel removed). Terminals
+ * declare which of their matched values are deprecated via [TerminalCombinator.deprecationFor].
+ */
+
+/** A deprecated token at `[start, end)` in the value, with the reason to show. */
+data class DeprecatedToken(val start: Int, val end: Int, val message: String)
+
+/**
+ * Deprecated tokens in [value], taken from the first full parse. Empty if the value doesn't fully
+ * parse (an invalid value is the InvalidValue inspection's job; deprecation is reported once valid).
+ */
+fun Combinator.deprecatedTokens(value: String): List<DeprecatedToken> {
+  // Require a fully-valid parse: don't pile a deprecation note on top of an otherwise invalid value.
+  val parse = parse(value, 0).filterIsInstance<Parse>()
+    .firstOrNull { it.end == value.length && it.tokens.all { token -> token.valid } } ?: return emptyList()
+  return parse.tokens.mapNotNull { token ->
+    token.terminal.deprecationFor(token.text)?.let { DeprecatedToken(token.start, token.end, it) }
+  }
+}

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/semanticdata/optionvalues/grammar/FlexibleLiteralChoiceTerminal.kt

@@ -8,6 +8,16 @@ class FlexibleLiteralChoiceTerminal(vararg val choices: String) : TerminalCombin
     choices.sortBy { -it.length }
   }
 
+  private var deprecations: Map<String, String> = emptyMap()
+
+  /** Mark some choices as valid-but-deprecated (choice -> reason). Returns this for chaining. */
+  fun deprecating(deprecations: Map<String, String>): FlexibleLiteralChoiceTerminal {
+    this.deprecations = deprecations
+    return this
+  }
+
+  override fun deprecationFor(token: String): String? = deprecations[token]
+
   val syntaticMatch: Regex
 
   init {

src/main/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/semanticdata/optionvalues/grammar/TerminalCombinator.kt

@@ -4,4 +4,10 @@ interface TerminalCombinator : Combinator {
   override fun toStringIndented(indent: Int): String {
     return toString()
   }
+
+  /**
+   * A message if [token] (a value this terminal matched) is valid but deprecated, else null.
+   * Lets a grammar flag accepted-but-obsolete values (e.g. kernel-removed address families).
+   */
+  fun deprecationFor(token: String): String? = null
 }

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

@@ -60,6 +60,7 @@
     <annotator language="Unit File (systemd)" implementationClass="net.sjrx.intellij.plugins.systemdunitfiles.annotators.LineContinuationCharacterFollowedByWhitespaceAnnotator"/>
     <annotator language="Unit File (systemd)" implementationClass="net.sjrx.intellij.plugins.systemdunitfiles.annotators.PropertyIsNotInSectionAnnotator"/>
     <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"/>
     <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/DeprecatedGrammarValueAnnotatorTest.kt

@@ -0,0 +1,46 @@
+package net.sjrx.intellij.plugins.systemdunitfiles.annotators
+
+import com.intellij.codeInsight.daemon.impl.HighlightInfo
+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
+
+/** End-to-end: a kernel-removed address family gets a weak warning (behind the flag). */
+class DeprecatedGrammarValueAnnotatorTest : AbstractUnitFileTest() {
+
+  override fun tearDown() {
+    try {
+      ExperimentalSettings.getInstance(project).state.useGrammarParseEngine = false
+    } finally {
+      super.tearDown()
+    }
+  }
+
+  private fun enableNewEngine() {
+    ExperimentalSettings.getInstance(project).state.useGrammarParseEngine = true
+  }
+
+  private fun weakWarned(highlights: List<HighlightInfo>, text: String) =
+    highlights.any { it.severity == HighlightSeverity.WEAK_WARNING && it.text == text }
+
+  @Test
+  fun testRemovedFamilyIsWeakWarned() {
+    enableNewEngine()
+    setupFileInEditor("file.service", "[Service]\nRestrictAddressFamilies=AF_INET AF_DECnet")
+    assertTrue(weakWarned(myFixture.doHighlighting(), "AF_DECnet"))
+  }
+
+  @Test
+  fun testCurrentFamilyIsNotWarned() {
+    enableNewEngine()
+    setupFileInEditor("file.service", "[Service]\nRestrictAddressFamilies=AF_INET")
+    assertFalse(weakWarned(myFixture.doHighlighting(), "AF_INET"))
+  }
+
+  @Test
+  fun testNoWarningWhenFlagOff() {
+    setupFileInEditor("file.service", "[Service]\nRestrictAddressFamilies=AF_DECnet")
+    assertFalse(weakWarned(myFixture.doHighlighting(), "AF_DECnet"))
+  }
+}

src/test/kotlin/net/sjrx/intellij/plugins/systemdunitfiles/semanticdata/optionvalues/grammar/DeprecationsTest.kt

@@ -0,0 +1,46 @@
+package net.sjrx.intellij.plugins.systemdunitfiles.semanticdata.optionvalues.grammar
+
+import net.sjrx.intellij.plugins.systemdunitfiles.semanticdata.optionvalues.ai.ConfigParseAddressFamiliesOptionValue
+import net.sjrx.intellij.plugins.systemdunitfiles.semanticdata.optionvalues.ai.ConfigParseIpMasqueradeOptionValue
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/** Unit tests for valid-but-deprecated value detection on the RestrictAddressFamilies grammar. */
+class DeprecationsTest {
+
+  private val grammar = ConfigParseAddressFamiliesOptionValue().combinator
+
+  @Test
+  fun testRemovedFamilyIsReportedAtItsExactSpan() {
+    val deprecated = grammar.deprecatedTokens("AF_INET AF_DECnet")
+    assertEquals(1, deprecated.size)
+    val it = deprecated.single()
+    assertEquals(8, it.start)  // "AF_INET " == 8 chars
+    assertEquals(17, it.end)   // + "AF_DECnet"
+    assertTrue(it.message.contains("AF_DECnet"))
+    assertTrue(it.message.contains("removed"))
+  }
+
+  @Test
+  fun testCurrentFamiliesAreNotReported() {
+    assertTrue(grammar.deprecatedTokens("AF_INET AF_INET6 AF_UNIX").isEmpty())
+  }
+
+  @Test
+  fun testInvalidValueReportsNoDeprecations() {
+    // No full parse -> nothing (the InvalidValue inspection handles the error instead).
+    assertTrue(grammar.deprecatedTokens("AF_DECnet AF_BOGUS").isEmpty())
+  }
+
+  @Test
+  fun testIpMasqueradeBooleanValuesAreDeprecated() {
+    // A second, unrelated user of the same layer: the legacy boolean forms of IPMasquerade= are
+    // accepted but deprecated in favour of ipv4/ipv6/both/no.
+    val ipMasquerade = ConfigParseIpMasqueradeOptionValue().combinator
+    assertTrue(ipMasquerade.deprecatedTokens("true").single().message.contains("ipv4"))
+    assertTrue(ipMasquerade.deprecatedTokens("off").single().message.contains("no"))
+    assertTrue(ipMasquerade.deprecatedTokens("ipv4").isEmpty())
+    assertTrue(ipMasquerade.deprecatedTokens("both").isEmpty())
+  }
+}