From f6ccd2e8a69891ffd7cbab6e861e55c1b79dea30 Mon Sep 17 00:00:00 2001 From: Anton Sviridov Date: Tue, 18 Mar 2025 14:30:46 +0000 Subject: [PATCH 1/2] Syntactic indexing public doc --- .../syntactic_code_navigation.mdx | 42 +++++++++++++++++++ src/data/navigation.ts | 1 + 2 files changed, 43 insertions(+) create mode 100644 docs/code-search/code-navigation/syntactic_code_navigation.mdx diff --git a/docs/code-search/code-navigation/syntactic_code_navigation.mdx b/docs/code-search/code-navigation/syntactic_code_navigation.mdx new file mode 100644 index 000000000..26291cf61 --- /dev/null +++ b/docs/code-search/code-navigation/syntactic_code_navigation.mdx @@ -0,0 +1,42 @@ +# Syntactic Code Navigation + + + Supported on [Enterprise](/pricing/enterprise) plans. + + This feature is currently experimental and enabled by default for Cloud customers + + + +Syntactic code navigation is an opt-in zero configuration feature that improves code navigation for certain languages in the absence of +[Precise code navigation](./precise_code_navigation) set up. It works by periodically indexing repositories for which it is [enabled](#enabling-syntactic-code-navigation), using high level syntax analysis heuristics. + +This mechanism is more robust than search-based navigation, but less powerful than Precise code navigation. +When syntactic indexing data is available for a given file and repository, it will be selected over search-based navigation automatically, +but only if Precise data is not available. To summarise the order of priorities is as follows: + +- Precise data +- Syntactic, if no precise data available +- Search-based, if no syntactic available + +## Enabling Syntactic code navigation + +First, enable the experimental feature flag in Site config: + +```json + "experimentalFeatures.codeintelSyntacticIndexing.enabled": true +``` + +Next, you need to ensure that syntactic indexing is enabled in a code graph configuration policy. Note that for cloud customers this feature is enabled by default for all repositories, as part of +automatically managed policy called `[Sourcegraph Managed] Head of default branch policy`. + +For all other deployments, you will need to create a HEAD policy with "Syntactic indexing" enabled: + +![Screenshot of sourcegraph interface demonstrating Syntactic indexing toggle enabled for a code graph policy](https://storage.googleapis.com/sourcegraph-assets/Docs/syntactic-indexing-policy.png) + +Syntactic indexing can only be enabled if the policy type is set to HEAD – only indexing the tip of default branch on each repository. You may choose to apply this policy only to selected repositories, although the recommendation is to enable it instance-wide. + +## Supported languages + +Syntactic code navigation requires language-specific implementations, and we currently support the following languages: [Java](https://www.java.com/en/), [Go](https://go.dev/), [Scala](https://scala-lang.org). + +We are constantly looking to expand the list of supported languages, with Python, Typescript/Javascript, C, C++, C# planned. If you are interested in syntactic indexing for these or any other languages, please contact your Sourcegraph account representative. diff --git a/src/data/navigation.ts b/src/data/navigation.ts index e2bf52c36..a9ccccb54 100644 --- a/src/data/navigation.ts +++ b/src/data/navigation.ts @@ -105,6 +105,7 @@ export const navigation: NavigationItem[] = [ { title: "Features", href: "/code-search/code-navigation/features", }, { title: "Search-based code navigation", href: "/code-search/code-navigation/search_based_code_navigation", }, { title: "Precise code navigation", href: "/code-search/code-navigation/precise_code_navigation", }, + { title: "Syntactic code navigation", href: "/code-search/code-navigation/syntactic_code_navigation", }, { title: "Auto-indexing", href: "/code-search/code-navigation/auto_indexing", }, { title: "Environment Variables", href: "/code-search/code-navigation/envvars", }, { title: "Troubleshooting", href: "/code-search/code-navigation/troubleshooting", }, From 49a223155d8ad20e565f4e9e8f24a6ca3778e727 Mon Sep 17 00:00:00 2001 From: Anton Sviridov Date: Wed, 23 Apr 2025 15:18:21 +0100 Subject: [PATCH 2/2] PR comments --- .../syntactic_code_navigation.mdx | 27 +++++++++++++++---- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/code-search/code-navigation/syntactic_code_navigation.mdx b/docs/code-search/code-navigation/syntactic_code_navigation.mdx index 26291cf61..f186daa1f 100644 --- a/docs/code-search/code-navigation/syntactic_code_navigation.mdx +++ b/docs/code-search/code-navigation/syntactic_code_navigation.mdx @@ -3,16 +3,16 @@ Supported on [Enterprise](/pricing/enterprise) plans. - This feature is currently experimental and enabled by default for Cloud customers + This feature is currently in Beta and enabled by default for Cloud customers -Syntactic code navigation is an opt-in zero configuration feature that improves code navigation for certain languages in the absence of +Syntactic code navigation is a zero configuration feature that improves code navigation for certain languages in the absence of [Precise code navigation](./precise_code_navigation) set up. It works by periodically indexing repositories for which it is [enabled](#enabling-syntactic-code-navigation), using high level syntax analysis heuristics. This mechanism is more robust than search-based navigation, but less powerful than Precise code navigation. When syntactic indexing data is available for a given file and repository, it will be selected over search-based navigation automatically, -but only if Precise data is not available. To summarise the order of priorities is as follows: +but only if Precise data is not available. To summarize, the order of priorities is as follows: - Precise data - Syntactic, if no precise data available @@ -37,6 +37,23 @@ Syntactic indexing can only be enabled if the policy type is set to HEAD – onl ## Supported languages -Syntactic code navigation requires language-specific implementations, and we currently support the following languages: [Java](https://www.java.com/en/), [Go](https://go.dev/), [Scala](https://scala-lang.org). +Syntactic code navigation requires language-specific implementations, and we currently support the following languages: -We are constantly looking to expand the list of supported languages, with Python, Typescript/Javascript, C, C++, C# planned. If you are interested in syntactic indexing for these or any other languages, please contact your Sourcegraph account representative. + - [Java](https://www.java.com/en/) + - [Go](https://go.dev/) + - [Scala](https://scala-lang.org) + - [C#](https://learn.microsoft.com/en-us/dotnet/csharp/) + - [C++](https://isocpp.org/) + +We are constantly looking to expand the list of supported languages, with Python, Typescript/Javascript, and C planned. +If you are interested in syntactic indexing for these or any other languages, please contact your Sourcegraph account representative. + +## Comparison with Precise and Search-based + +Syntactic code navigation falls between Precise and Search-based code navigation both in terms of quality of navigation, +and in terms of effort to maintain for different languages: + +![Comparison chart showing where different navigation modes are located in terms of effort to maintain and quality of results](https://storage.googleapis.com/sourcegraph-assets/Docs/code-navigation-levels-comparison.png) + +As the indexing does not involve build tools or actual compilers, it can be performed in isolated environment, with no network access +and no configuration, unlike Precise.