feat: add semantic token modes

Default semantic tokens to a contextual stream so editor syntax grammars remain in charge of ordinary PHP highlighting. Keep the previous broad stream available with full mode and provide an off switch for users who want no LSP semantic highlighting.\n\nDocument the new setting in the configuration reference and schema.

Author: calebdw

config-schema.json

@@ -86,6 +86,22 @@
         }
       }
     },
+    "semantic_tokens": {
+      "type": "object",
+      "description": "Controls LSP semantic token highlighting.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "description": "Semantic token emission mode. \"contextual\" emits only context-sensitive tokens that complement editor syntax highlighting. \"full\" emits the complete semantic token stream. \"off\" disables semantic tokens.",
+          "enum": [
+            "contextual",
+            "full",
+            "off"
+          ],
+          "default": "contextual"
+        }
+      }
+    },
     "laravel": {
       "type": "object",
       "description": "Laravel-specific analysis settings.",

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Semantic token modes.** `.phpantom.toml` now supports `[semantic_tokens] mode = "contextual" | "full" | "off"`. The default `contextual` mode emits only context-sensitive highlighting that complements editor syntax grammars, while `full` keeps the previous broad semantic-token stream and `off` disables semantic tokens. Contributed by @calebdw.
 - **`@phpstan-ignore` identifiers are highlighted and completed.** PHPStan ignore comments now highlight the `@phpstan-ignore` tag and each listed error identifier in both docblocks and ordinary `//` comments. Identifier completion works inside the comma-separated ignore list, using PHPStan diagnostic codes already seen in the current file while staying out of per-code parenthesized reasons. Contributed by @calebdw.
 - **Parent member override completion.** Typing a method name after `function` in a class body (for example `protected function get`) now suggests public and protected methods from parent classes and interfaces that can still be overridden or implemented, inserting a full signature snippet. The same flow suggests parent properties after `$` (for example `protected $tit`) and parent constants after `const`. Snippets insert `#[\Override]` above methods on PHP 8.3+, properties on PHP 8.5+, and constants on PHP 8.6+ (from `composer.json` / `config.platform.php`). Private members and ones already defined on the class are omitted. Contributed by @calebdw.
 - **Reference and implementation count inlay hints.** Classes, interfaces, traits, enums, methods, properties, and constants now show reference counts (e.g. "3 references") as inlay hints. Interfaces and abstract classes additionally show implementation counts (e.g. "2 implementations"). Counts are derived from the cross-file reference index and the go-to-implementation reverse inheritance index, so they are fast even on large codebases. Private members, magic methods, and overridden members are omitted to keep the annotations focused. Contributed by @calebdw.
@@ -42,6 +43,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Deprecated enum cases are recognized.** Enum cases annotated with `@deprecated` or `#[Deprecated]` now carry deprecation metadata, so usages like `self::Low` can be highlighted as deprecated in contextual semantic-token mode. Contributed by @calebdw.
+- **Class constant accesses use constant semantic highlighting.** `self::CONSTANT`, `static::CONSTANT`, `parent::CONSTANT`, and `ClassName::CONSTANT` now emit the `enumMember` semantic token instead of being colored as properties, while `ClassName::$property` still emits `property`. Contributed by @calebdw.
 - **PHP attributes use decorator semantic highlighting.** Attribute class names in `#[...]` now emit the `decorator` semantic token instead of `class`, so editor themes can color attributes differently from normal class references. Contributed by @calebdw.
 - **Go-to-definition on overriding methods jumps to the parent declaration.** When the cursor is on a method definition that overrides a parent or implements an interface method, go-to-definition now navigates to the prototype declaration instead of returning call-site references. Similarly, go-to-definition on a class name jumps to the parent class when one exists. Methods and classes that don't override anything still show usages as before. Contributed by @calebdw.
 - **Go-to-definition on overridden properties and constants jumps to the prototype declaration.** Declaration-site navigation now follows overridden properties and constants to the nearest parent or trait declaration, matching the override behavior for methods. Contributed by @calebdw.

docs/configuration.md

@@ -62,6 +62,21 @@ message = "^Call to deprecated function some_legacy_helper\\(\\)"
 | ---------- | ------ | -------- | ----------- |
 | `strategy` | string | `"full"` | Class discovery strategy: `"full"`, `"composer"`, `"self"`, or `"none"`. See [Indexing Strategy](#indexing-strategy) below. |
 
+### `[semantic_tokens]`
+
+PHPantom defaults to `contextual` semantic tokens so editor syntax
+highlighting remains in charge of ordinary PHP syntax.
+
+| Key    | Type   | Default        | Description |
+| ------ | ------ | -------------- | ----------- |
+| `mode` | string | `"contextual"` | Semantic token mode: `"contextual"`, `"full"`, or `"off"`. |
+
+| Mode | Behaviour |
+| --- | --- |
+| `"contextual"` | Emit only context-sensitive tokens that complement Tree-sitter/TextMate highlighting, such as parameters, PHPDoc template parameters, deprecated references, and static member accesses. |
+| `"full"` | Emit the complete semantic token stream, including ordinary classes, variables, functions, methods, properties, comments, keywords, attributes, and Blade tokens. |
+| `"off"` | Return no semantic tokens. |
+
 ### `[formatting]`
 
 | Key            | Type    | Default | Description |

src/config.rs

@@ -25,6 +25,8 @@ pub struct Config {
     pub diagnostics: DiagnosticsConfig,
     /// Indexing strategy and file discovery settings.
     pub indexing: IndexingConfig,
+    /// Semantic token highlighting settings.
+    pub semantic_tokens: SemanticTokensConfig,
     /// Formatting proxy settings.
     pub formatting: FormattingConfig,
     /// PHPStan proxy settings.
@@ -37,6 +39,65 @@ pub struct Config {
     pub laravel: LaravelConfig,
 }
 
+/// `[semantic_tokens]` section — controls LSP semantic highlighting.
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(default)]
+pub struct SemanticTokensConfig {
+    /// Semantic token emission mode.
+    ///
+    /// - `"contextual"` (default) — emit only context-sensitive tokens
+    ///   that syntax grammars usually cannot infer.
+    /// - `"full"` — emit the complete semantic token stream.
+    /// - `"off"` — return no semantic tokens.
+    pub mode: Option<SemanticTokensMode>,
+}
+
+impl SemanticTokensConfig {
+    pub fn mode(&self) -> SemanticTokensMode {
+        self.mode.unwrap_or_default()
+    }
+}
+
+/// Semantic token emission mode.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum SemanticTokensMode {
+    /// Emit only context-sensitive tokens that complement editor syntax highlighting.
+    #[default]
+    Contextual,
+    /// Emit every token PHPantom can classify.
+    Full,
+    /// Disable semantic tokens.
+    Off,
+}
+
+impl<'de> Deserialize<'de> for SemanticTokensMode {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let s = String::deserialize(deserializer)?;
+        match s.as_str() {
+            "contextual" => Ok(SemanticTokensMode::Contextual),
+            "full" => Ok(SemanticTokensMode::Full),
+            "off" => Ok(SemanticTokensMode::Off),
+            other => Err(serde::de::Error::unknown_variant(
+                other,
+                &["contextual", "full", "off"],
+            )),
+        }
+    }
+}
+
+impl std::fmt::Display for SemanticTokensMode {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            SemanticTokensMode::Contextual => write!(f, "contextual"),
+            SemanticTokensMode::Full => write!(f, "full"),
+            SemanticTokensMode::Off => write!(f, "off"),
+        }
+    }
+}
+
 #[derive(Debug, Clone, Default, Deserialize)]
 #[serde(default)]
 pub struct LaravelConfig {
@@ -667,6 +728,10 @@ mod tests {
         assert!(!config.diagnostics.report_magic_properties_enabled());
         assert!(config.diagnostics.ignore.is_empty());
         assert_eq!(config.indexing.strategy(), IndexingStrategy::Full);
+        assert_eq!(
+            config.semantic_tokens.mode(),
+            SemanticTokensMode::Contextual
+        );
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
         assert!(config.formatting.timeout.is_none());
@@ -697,6 +762,10 @@ mod tests {
         assert!(!config.diagnostics.report_magic_properties_enabled());
         assert!(config.diagnostics.ignore.is_empty());
         assert_eq!(config.indexing.strategy(), IndexingStrategy::Full);
+        assert_eq!(
+            config.semantic_tokens.mode(),
+            SemanticTokensMode::Contextual
+        );
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
         assert!(config.phpstan.command.is_none());
@@ -715,6 +784,10 @@ mod tests {
         assert!(!config.diagnostics.extra_arguments_enabled());
         assert!(!config.diagnostics.report_magic_properties_enabled());
         assert_eq!(config.indexing.strategy(), IndexingStrategy::Full);
+        assert_eq!(
+            config.semantic_tokens.mode(),
+            SemanticTokensMode::Contextual
+        );
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
         assert!(config.phpstan.command.is_none());
@@ -959,6 +1032,9 @@ message = "^Call to deprecated function some_legacy_helper\\(\\)"
 [indexing]
 strategy = "self"
 
+[semantic_tokens]
+mode = "full"
+
 [formatting]
 php-cs-fixer = ""
 phpcbf = "/usr/local/bin/phpcbf"
@@ -996,6 +1072,7 @@ analyze-timeout = 45000
             Some("deprecated_usage")
         );
         assert_eq!(config.indexing.strategy, Some(IndexingStrategy::SelfScan));
+        assert_eq!(config.semantic_tokens.mode, Some(SemanticTokensMode::Full));
         assert_eq!(config.formatting.php_cs_fixer.as_deref(), Some(""));
         assert_eq!(
             config.formatting.phpcbf.as_deref(),
@@ -1029,6 +1106,45 @@ analyze-timeout = 45000
         assert_eq!(config.indexing.strategy, Some(IndexingStrategy::Composer));
     }
 
+    #[test]
+    fn parses_semantic_tokens_mode_contextual() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[semantic_tokens]\nmode = \"contextual\"\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert_eq!(
+            config.semantic_tokens.mode(),
+            SemanticTokensMode::Contextual
+        );
+    }
+
+    #[test]
+    fn parses_semantic_tokens_mode_full() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[semantic_tokens]\nmode = \"full\"\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert_eq!(config.semantic_tokens.mode(), SemanticTokensMode::Full);
+    }
+
+    #[test]
+    fn parses_semantic_tokens_mode_off() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[semantic_tokens]\nmode = \"off\"\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert_eq!(config.semantic_tokens.mode(), SemanticTokensMode::Off);
+    }
+
+    #[test]
+    fn invalid_semantic_tokens_mode_returns_parse_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[semantic_tokens]\nmode = \"bogus\"\n").unwrap();
+        let result = load_config(dir.path());
+        assert!(result.is_err());
+    }
+
     #[test]
     fn parses_laravel_schema_options() {
         let dir = tempfile::tempdir().unwrap();

src/parser/classes.rs

@@ -1425,6 +1425,17 @@ impl Backend {
                     }
                 }
                 ClassLikeMember::EnumCase(enum_case) => {
+                    let case_docblock_text = doc_ctx.and_then(|ctx| {
+                        docblock::get_docblock_text_for_node(ctx.trivias, ctx.content, member)
+                    });
+                    let case_docblock_info =
+                        case_docblock_text.and_then(docblock::parse_docblock_for_tags);
+                    let depr_info = {
+                        let docblock_msg = case_docblock_info
+                            .as_ref()
+                            .and_then(docblock::extract_deprecation_message_from_info);
+                        merge_deprecation_info(docblock_msg, &enum_case.attribute_lists, doc_ctx)
+                    };
                     let case_name = atom_bytes(enum_case.item.name().value);
                     let case_name_offset = enum_case.item.name().span.start.offset;
                     let enum_value = if let EnumCaseItem::Backed(backed) = &enum_case.item {
@@ -1441,8 +1452,8 @@ impl Backend {
                         name_offset: case_name_offset,
                         type_hint: None,
                         visibility: Visibility::Public,
-                        deprecation_message: None,
-                        deprecated_replacement: None,
+                        deprecation_message: depr_info.message,
+                        deprecated_replacement: depr_info.replacement,
                         see_refs: Vec::new(),
                         description: None,
                         is_enum_case: true,