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..f186daa1f --- /dev/null +++ b/docs/code-search/code-navigation/syntactic_code_navigation.mdx @@ -0,0 +1,59 @@ +# Syntactic Code Navigation + + + Supported on [Enterprise](/pricing/enterprise) plans. + + This feature is currently in Beta and enabled by default for Cloud customers + + + +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 summarize, 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) + - [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. 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", },