fix: respect includeDeclaration in references

docs/src/content/docs/en/user-guide/features/references.mdx

@@ -45,6 +45,18 @@ Vide searches references in all Verilog/SystemVerilog files scanned from the wor
 
 After `vide.toml` is configured, reference search follows the project scope described by `sources` and `libraries`, and uses include directories and macro definitions to decide which files participate in analysis.
 
+## Result Display
+
+By default, the references view also includes the declaration location so you can confirm where the symbol comes from. If you want usage locations only, add this to VS Code Settings:
+
+```json
+{
+  "vide.references.includeDeclaration": false
+}
+```
+
+See [Scope settings](../../vscode-settings/#scope) for the full reference.
+
 ## Relationship to Rename
 
 Find References only shows locations and does not modify files. Rename edits declarations and references, so it usually needs `vide.toml` to make the editable project scope explicit.

docs/src/content/docs/en/user-guide/vscode-settings.mdx

@@ -16,6 +16,7 @@ All settings are under the `vide.*` namespace. Search for `Vide` in the VS Code
 | Point VS Code at a local Qihe executable | `vide.qihe.command` |
 | Point Vide at `verible-verilog-format` | `vide.formatter.path` |
 | Refresh diagnostics on save or while typing | `vide.diagnostics.update` |
+| Show usage locations only in Find References | `vide.references.includeDeclaration` |
 | Toggle port, parameter, and end-structure annotations | `vide.inlayHints.*` |
 | Toggle instance-count annotations above module declarations | `vide.lens.instantiations.enable` |
 | Refresh project information after configuration changes | `vide.workspace.auto.reload` |
@@ -71,11 +72,14 @@ Related docs: [Configure the First Project](../first-project/) and [Project Conf
 
 ## Scope
 
-This setting affects local-symbol visibility in find references, rename, and document highlights. Keep the default when unsure.
+These settings affect local-symbol visibility in find references, rename, and document highlights, and whether the declaration location is included in reference results. Keep the defaults when unsure.
 
 Related features: [Find References](../features/references/) and [Rename](../features/rename/).
 
-<VscodeSettingsTable locale="en" settings={['vide.scope.visibility']} />
+<VscodeSettingsTable
+  locale="en"
+  settings={['vide.scope.visibility', 'vide.references.includeDeclaration']}
+/>
 
 ## Formatter and Formatting
 

docs/src/content/docs/user-guide/features/references.mdx

@@ -44,3 +44,15 @@ Vide 会在工作区扫描到的所有 Verilog/SystemVerilog 文件中查找引
 ### 有完整配置时
 
 写好 `vide.toml` 后，引用搜索会按 `sources` 和 `libraries` 描述的工程范围执行，并结合 include 目录和宏定义判断实际参与分析的文件。
+
+## 结果显示
+
+默认情况下，引用结果会把声明位置一起显示，方便你从列表里确认符号是从哪里引入的。如果你只想看真正的使用位置，可以在 VS Code Settings 中写：
+
+```json
+{
+  "vide.references.includeDeclaration": false
+}
+```
+
+完整参考见 [Scope 设置](../../vscode-settings/#scope)。

docs/src/content/docs/user-guide/vscode-settings.mdx

@@ -16,6 +16,7 @@ VS Code 设置控制编辑器里的行为，例如诊断刷新、Qihe 命令、
 | 让 VS Code 调用本机的 Qihe | `vide.qihe.command` |
 | 指定本机的 `verible-verilog-format` | `vide.formatter.path` |
 | 控制诊断刷新是保存后还是输入时 | `vide.diagnostics.update` |
+| 让引用搜索只显示实际使用位置 | `vide.references.includeDeclaration` |
 | 开关端口、参数、结构结尾的代码注解 | `vide.inlayHints.*` |
 | 开关模块声明上方的实例数量注解 | `vide.lens.instantiations.enable` |
 | 项目配置变化后是否自动刷新 | `vide.workspace.auto.reload` |
@@ -71,11 +72,14 @@ VS Code 设置控制编辑器里的行为，例如诊断刷新、Qihe 命令、
 
 ## Scope
 
-这组设置会影响引用搜索、重命名和当前位置高亮里的局部符号可见性；常规使用保持默认值即可。
+这组设置会影响引用搜索、重命名和当前位置高亮里的局部符号可见性，以及引用搜索是否把声明位置一起显示；常规使用保持默认值即可。
 
 相关功能：[引用搜索](../features/references/) 和 [重命名](../features/rename/)。
 
-<VscodeSettingsTable locale="zh" settings={['vide.scope.visibility']} />
+<VscodeSettingsTable
+  locale="zh"
+  settings={['vide.scope.visibility', 'vide.references.includeDeclaration']}
+/>
 
 ## Formatter 和 Formatting
 

editors/vscode/package.json

@@ -199,6 +199,11 @@
           "default": "private",
           "description": "%configuration.scope.visibility.description%"
         },
+        "vide.references.includeDeclaration": {
+          "type": "boolean",
+          "default": true,
+          "description": "%configuration.references.includeDeclaration.description%"
+        },
         "vide.formatter.provider": {
           "type": "string",
           "enum": [

editors/vscode/package.nls.json

@@ -16,6 +16,7 @@
   "configuration.files.watcher.description": "Controls how Vide watches project files.",
   "configuration.workspace.auto.reload.description": "Automatically refresh project information when project manifests change.",
   "configuration.scope.visibility.description": "Controls whether symbols inside scopes, except ports, are visible outside those scopes.",
+  "configuration.references.includeDeclaration.description": "Include declarations when finding references.",
   "configuration.formatter.provider.enum.verible": "Use an external verible-verilog-format executable. Supports Format Document and Format Selection.",
   "configuration.formatter.provider.description": "Formatter backend used by Vide.",
   "configuration.formatter.path.description": "Path to verible-verilog-format when vide.formatter.provider is verible. Leave empty to find it on PATH.",

editors/vscode/package.nls.zh-cn.json

@@ -16,6 +16,7 @@
   "configuration.files.watcher.description": "控制 Vide 如何监视项目文件。",
   "configuration.workspace.auto.reload.description": "项目配置文件变化时自动刷新项目信息。",
   "configuration.scope.visibility.description": "控制作用域内除端口以外的符号是否在作用域外可见。",
+  "configuration.references.includeDeclaration.description": "查找引用时是否包含声明位置。",
   "configuration.formatter.provider.enum.verible": "使用外部 verible-verilog-format 可执行文件。支持格式化文档和格式化选区。",
   "configuration.formatter.provider.description": "Vide 使用的格式化后端。",
   "configuration.formatter.path.description": "当 vide.formatter.provider 为 verible 时，verible-verilog-format 的路径。留空则从 PATH 中查找。",

editors/vscode/src/extension.ts

@@ -381,6 +381,14 @@ function readConfiguration(): ServerConfiguration {
   };
 }
 
+function includeDeclarationInReferences(document: vscode.TextDocument): boolean {
+  return (
+    vscode.workspace
+      .getConfiguration('vide', document)
+      .get<boolean>('references.includeDeclaration') ?? true
+  );
+}
+
 function resolveWorkingDirectory(
   context: vscode.ExtensionContext,
   configuredCwd: string | undefined,
@@ -649,6 +657,12 @@ async function createClient(context: vscode.ExtensionContext): Promise<LanguageC
     traceOutputChannel: channel,
     revealOutputChannelOn: RevealOutputChannelOn.Never,
     initializationOptions: serverInitializationOptions(vscode.workspace.getConfiguration('vide')),
+    middleware: {
+      provideReferences: async (document, position, options, token, next) => {
+        options.includeDeclaration = includeDeclarationInReferences(document);
+        return await next(document, position, options, token);
+      },
+    },
     ...(config.trace !== 'off' && { trace: config.trace }),
   };
 

editors/vscode/test/configuration.test.ts

@@ -90,6 +90,7 @@ test('contributes settings for the complete Vide user configuration surface', ()
     'vide.files.watcher',
     'vide.workspace.auto.reload',
     'vide.scope.visibility',
+    'vide.references.includeDeclaration',
     'vide.formatter.provider',
     'vide.formatter.path',
     'vide.formatter.args',

src/global_state/handlers/request.rs

@@ -347,6 +347,7 @@ pub(crate) fn handle_references(
     snap: GlobalStateSnapshot,
     params: lsp_types::ReferenceParams,
 ) -> anyhow::Result<Option<Vec<lsp_types::Location>>> {
+    let include_declaration = params.context.include_declaration;
     let position = from_proto::file_position(&snap, params.text_document_position)?;
     let config = snap.config.references();
     let Some(refs) = snap.analysis.references(position, config)? else {
@@ -356,9 +357,8 @@ pub(crate) fn handle_references(
     let locations = refs
         .into_iter()
         .flat_map(|References { def, refs }| {
-            let decl = def
+            let decl = if include_declaration { def.unwrap_or_default() } else { Vec::new() }
                 .into_iter()
-                .flatten()
                 .map(|nav| FileRange { file_id: nav.file_id, range: nav.focus_or_full_range() });
 
             let refs = refs.into_iter().flat_map(|(file_id, refs)| {

src/tests.rs

@@ -420,6 +420,17 @@ fn request_reference_uris(
     text: &str,
     needle: &str,
     request_id: i32,
+) -> Vec<Url> {
+    request_reference_uris_with_include_declaration(client, uri, text, needle, request_id, true)
+}
+
+fn request_reference_uris_with_include_declaration(
+    client: &Connection,
+    uri: Url,
+    text: &str,
+    needle: &str,
+    request_id: i32,
+    include_declaration: bool,
 ) -> Vec<Url> {
     let request_id = lsp_server::RequestId::from(request_id);
     client
@@ -432,7 +443,7 @@ fn request_reference_uris(
                     text_document: TextDocumentIdentifier { uri },
                     position: position_of(text, needle),
                 },
-                context: lsp_types::ReferenceContext { include_declaration: true },
+                context: lsp_types::ReferenceContext { include_declaration },
                 work_done_progress_params: WorkDoneProgressParams::default(),
                 partial_result_params: Default::default(),
             },
@@ -3255,3 +3266,61 @@ fn include_expanded_parameter_decls_keep_module_navigation_available() {
 
     shutdown_test_server(&client, server_thread);
 }
+
+#[test]
+fn references_request_respects_include_declaration() {
+    let temp_dir = TempDir::new("references-include-declaration");
+    let rtl_dir = temp_dir.path().join("rtl");
+    fs::create_dir_all(&rtl_dir).unwrap();
+
+    let top_text = "module top;\n  child u_child();\nendmodule\n";
+    let child_text = "module child();\nendmodule\n";
+
+    fs::write(
+        temp_dir.path().join("vide.toml"),
+        "top_modules = [\"top\"]\nsources = [\"rtl/*.v\"]\ninclude_dirs = [\"rtl\"]\n",
+    )
+    .unwrap();
+    let top_path = rtl_dir.join("top.v");
+    let child_path = rtl_dir.join("child.v");
+    fs::write(&top_path, top_text).unwrap();
+    fs::write(&child_path, child_text).unwrap();
+
+    let root_path = temp_dir.path().to_path_buf();
+    let (client, server_thread) =
+        spawn_test_workspace(root_path, ClientCapabilities::default(), UserConfig::default());
+    let top_uri = to_proto::url_from_abs_path(top_path.as_path()).unwrap();
+    let child_uri = to_proto::url_from_abs_path(child_path.as_path()).unwrap();
+
+    open_test_document(&client, top_uri.clone(), top_text);
+    open_test_document(&client, child_uri.clone(), child_text);
+    let _ = request_document_diagnostics(&client, top_uri.clone(), 1);
+
+    let refs_with_decl = request_reference_uris_with_include_declaration(
+        &client,
+        child_uri.clone(),
+        child_text,
+        "child()",
+        2,
+        true,
+    );
+    assert!(
+        refs_with_decl.contains(&child_uri) && refs_with_decl.contains(&top_uri),
+        "include_declaration=true should include the declaration and instantiation: {refs_with_decl:?}"
+    );
+
+    let refs_without_decl = request_reference_uris_with_include_declaration(
+        &client,
+        child_uri.clone(),
+        child_text,
+        "child()",
+        3,
+        false,
+    );
+    assert!(
+        !refs_without_decl.contains(&child_uri) && refs_without_decl.contains(&top_uri),
+        "include_declaration=false should exclude the declaration while keeping instantiations: {refs_without_decl:?}"
+    );
+
+    shutdown_test_server(&client, server_thread);
+}