Code navigation (#315)

* Initial POC

* Add cursor style rule

* wip: resolve symbol definition in pop-up box

* further wip

* wip

* wip: started work on bottom panel

* wip: move find references to server action

* wip

* wip on fast readonly syntax highlighting using code mirror

* refactor things around

* Further wip: discovered that typical HighlightStyle.define highlighters cause performance problems when rendering thousands of code cells. The workaround found is to use tagHighlighter and rely on tailwind to drive theming in CSS.

* wip: Add line number suppoert to the readonly code block

* further wip: refactored how the bottom panel is rendered s.t., we don't need to re-render when doing a goto def

* perf: memoize highlight ranges to prevent unecessary re-renders

* chore: move search results list to use readonly ediotr

* rename readOnlyCodeBlock to lightweightCodeHighlighter

* improve syntax highlighting

* nits with keyboard shortcuts

* move match count aggregation into API layer

* wip on adding definitions tab to bottom panel

* Add eslint rule for tanstack query

* Improve how we communicate multiple symbol definitions

* Add support for revisions

* chore: move stylized resize handle into shared component

* chore: refactor code nav UI into ee

* chore: made /browse the default path when clicking on a search result. More cleanup.

* add code nav to preview panel

* small bug fixes

* wip: add scroll restoration to search results panel

* small nit improvements

* subtle changes to highlighting style

* Use word boundaries for references

* make bottom panel larger

* fix visual artifact issues with filter panel

* bidirectional filtering

* debug code

* Improve search heuristic by filtering by language

* Improved collapsed preview panel style

* add node types for a bunch of langs

* nit: add tooltip to focus search bar shortcut hint

* Add cmd+click to open preview panel

* feedback

* changelog

* posthog events

* wip on docs

* docs and changelog

* improve code nav search heuristics: search across repositories, and expand language filter to resolve related langs like TypeScript, JavaScript, TSX, and JSX.

* delete unused /references route

* improve search contexts news sub_header

---------

Co-authored-by: msukkari <[email protected]>

Author: brendan-kellam

.cursor/rules/style.mdc

@@ -0,0 +1,7 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+- Always use 4 spaces for indentation
+- Filenames should always be camelCase. Exception: if there are filenames in the same directory with a format other than camelCase, use that format to keep things consistent.

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- [Sourcebot EE] Added code navigation (find all references / go to definition). [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
+
+### Fixed
+- Improved scroll performance for large numbers of search results. [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
+
 ## [3.2.1] - 2025-05-15
 
 ### Added

docs/docs.json

@@ -50,7 +50,8 @@
                         "pages": [
                             "docs/search/syntax-reference",
                             "docs/search/multi-branch-indexing",
-                            "docs/search/search-contexts"
+                            "docs/search/search-contexts",
+                            "docs/search/code-navigation"
                         ]
                     },
                     {

docs/docs/search/code-navigation.mdx

@@ -0,0 +1,44 @@
+---
+title: Code navigation
+sidebarTitle: Code navigation (EE)
+---
+
+import SearchContextSchema from '/snippets/schemas/v3/searchContext.schema.mdx'
+
+<Note>
+This feature is only available with an active Enterprise license. Please add your [license key](/self-hosting/license-key) to activate it.
+</Note>
+
+**Code navigation** allows you to jump between symbol definition and references when viewing source files in Sourcebot. This feature is enabled **automatically** when a valid license key is present and works with all popular programming languages.
+
+
+<video src="https://framerusercontent.com/assets/B9ZxrlsUeO9NJyzkKyvVV2KSU4.mp4" className="w-full aspect-video" controls></video>
+
+## Features
+
+| Feature | Description |
+|:--------|:------------|
+| **Hover popover** | Hovering over a symbol reveals the symbol's definition signature as a inline preview. |
+| **Go to definition** | Clicking the "go to definition" button in the popover or clicking the symbol name navigates to the symbol's definition. |
+| **Find references** | Clicking the "find all references" button in the popover lists all references in the explore panel. |
+| **Explore panel** | Lists all references and definitions for the symbol selected in the popover. |
+
+## How does it work?
+
+Code navigation is **search-based**, meaning it uses the same code search engine and [query language](/docs/search/syntax-reference) to estimate a symbol's references and definitions. We refer to these estimations as "search heuristics". We have two search heuristics to enable the following operations:
+
+### Find references
+Given a `symbolName`, along with information about the file the symbol is contained within (`git_revision`, and `language`), runs the following search:
+
+```bash
+\\b{symbolName}\\b rev:{git_revision} lang:{language} case:yes
+```
+
+### Find definitions
+Given a `symbolName`, along with information about the file the symbol is contained within (`git_revision`, and `language`), runs the following search:
+
+```bash
+sym:\\b{symbolName}\\b rev:{git_revision} lang:{language}
+```
+
+Note that the `sym:` prefix is used to filter the search by symbol definitions. These are created at index time by [universal ctags](https://ctags.io/).

docs/images/demo.mp4

@@ -7,7 +7,8 @@
     "eslint:recommended",
     "plugin:@typescript-eslint/recommended",
     "plugin:react/recommended",
-    "next/core-web-vitals"
+    "next/core-web-vitals",
+    "plugin:@tanstack/query/recommended"
   ],
   "rules": {
     "react-hooks/exhaustive-deps": "warn",

packages/web/.eslintrc.json

@@ -34,6 +34,7 @@
     "@codemirror/lang-xml": "^6.1.0",
     "@codemirror/lang-yaml": "^6.1.2",
     "@codemirror/language": "^6.0.0",
+    "@codemirror/language-data": "^6.5.1",
     "@codemirror/legacy-modes": "^6.4.2",
     "@codemirror/search": "^6.5.6",
     "@codemirror/state": "^6.4.1",
@@ -81,6 +82,7 @@
     "@tanstack/react-query": "^5.53.3",
     "@tanstack/react-table": "^8.20.5",
     "@tanstack/react-virtual": "^3.10.8",
+    "@uidotdev/usehooks": "^2.4.1",
     "@uiw/codemirror-themes": "^4.23.6",
     "@uiw/react-codemirror": "^4.23.0",
     "@viz-js/lang-dot": "^1.0.4",
@@ -144,6 +146,7 @@
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
+    "@tanstack/eslint-plugin-query": "^5.74.7",
     "@types/micromatch": "^4.0.9",
     "@types/node": "^20",
     "@types/nodemailer": "^6.4.17",

packages/web/package.json

@@ -0,0 +1,12 @@
+# File browser
+
+This directory contains Sourcebot's file browser implementation. URL paths are used to determine what file the user wants to view. The following template is used:
+
+```sh
+/browse/<repo-name>[@<optional-revision-name>]/-/(blob|tree)/<path_to_file>
+```
+
+For example, to view `packages/backend/src/env.ts` in Sourcebot, we would use the following path:
+```sh
+/browse/github.com/sourcebot-dev/sourcebot@HEAD/-/blob/packages/backend/src/env.ts
+```