example 5

This report synthesizes information from multiple research items to provide a comprehensive overview of the GitLab epic gitlab-org/editor-extensions&58, focusing on its purpose, related merge requests, and the codebase areas affected, with particular attention to Rails code changes.

While a direct detailed report for the epic gitlab-org/editor-extensions&58 could not be generated, its scope, purpose, and implementation details have been extensively covered by reports on its related issues and merge requests.

1. What is this Epic About?

The epic gitlab-org/editor-extensions&58 (closed) is titled "Imports Context Provider - (previously DaVinci phase 2)"

Purpose and Scope: The primary goal of this epic is to enhance the accuracy and relevance of GitLab Duo Code Suggestions (and potentially other AI features) by providing the AI model with richer, more comprehensive context.

Problem Addressed: Previously, Code Suggestions primarily relied on the content of the currently open file and the cursor's position. This limited the AI's understanding of the broader project structure, dependencies, and related code, which could lead to less accurate or less helpful suggestions, especially in complex projects or files with numerous imports.

Solution: The epic proposed and implemented a new AI context provider within the GitLab Language Server (gitlab-lsp). This provider leverages code import analysis, typically using Abstract Syntax Tree (AST) parsing, to identify files imported by the user's current code. The content of these imported files is then included as additional context for the AI model.

As stated in the epic's description (quoted in multiple reports, e.g., Report 2, 3, 7, 8, 10):

The Problem We Are Solving

We aim to create a new AI context provider that utilizes the AI Context Management blueprint and Code Import analysis on the Language Server to provide additional context for Code Suggestions and other AI Features.

Code Suggestions currently uses open files and cursor context to show suggestions. Adding import statement analysis will provide better context about related files and dependencies.

This resolution strategy for the Advancer Context Resolver (DaVinci) Project focuses on file imports. It leverages the AST (Abstract Syntax Tree) to provide contextual awareness to AI models. For a full explanation of AST, please see the AST Proposal Issue.

You can find a demo of the initial proposal here: Demo

Key Objectives and Features:

  • Develop ImportContextProvider: Create the core logic for identifying, resolving, and fetching content from imported files.
  • Language Support: The initial iteration focused on ECMAScript compatible languages (JavaScript, TypeScript, Vue), with an architecture designed for future expansion to other languages.
  • Import Resolution: Handle various import types, including relative paths, non-relative paths (e.g., node_modules), workspace aliases, and custom aliases defined in tsconfig.json or jsconfig.json.
  • Integration: Integrate the new context provider into the existing AI Context Management framework and Code Suggestions workflow within gitlab-lsp. This included refactoring context processing pipelines for modularity and performance.
  • Feature Flagging: Control the rollout of the feature using the code_suggestions_include_context_imports feature flag.
  • Telemetry: Update telemetry to track the usage, performance (latency), and impact (e.g., acceptance rate) of this new context source.
  • Documentation: Update user-facing documentation to inform users about this enhancement.

The epic is part of a broader effort to improve Code Suggestions quality, such as the "Code Creation Duo Prioritization - Accuracy" epic (gitlab-org&14053).

2. What are all the Merge Requests related to this epic?

Numerous merge requests across different projects contributed to the implementation and support of the Imports Context Provider. Here's a categorized list of key MRs:

Core Logic & Language Server (gitlab-org/editor-extensions/gitlab-lsp):

  • Initial Implementation & Abstraction:
    • !1311: Draft: feat: ImportContextProvider (Early draft and architecture).
    • !1321: chore: introduce AbstractImportHandler (Foundation for language-specific import handling).
    • !1322: chore: introduce JavascriptImportResolver (Resolver for ECMAScript imports).
    • !1323: chore: introduce JavascripttImportStore (In-memory store for JS/TS/Vue files).
    • !1324: chore: add relative module support for JavascriptImportResolver (Support for relative imports).
    • !1325: feat: introduce ImportContextProvider (Formal introduction of the provider).
  • Non-Relative & Advanced Import Resolution:
    • !1372: feat: add non-relative import path resolution for code suggestions (Support for node_modules, workspace imports using enhanced-resolve).
    • !1398: feat: use projects tsconfig or jsconfig when resolving module imports (Respecting tsconfig.json/jsconfig.json).
    • !1504: feat: support resolving Node.js built-in module imports (Handling Node.js built-ins).
  • Context Management & Refactoring:
    • !1278: chore: make SuggestionService use OpenTabsProvider (Broader context management changes).
    • !1377: refactor: ai context item retrieval (Refactoring context item retrieval).
    • !1402: feat: add context-ranking processor (Introduced ContextRanker).
    • !1421: fix: export AIContextSearchRequest type (Type export fix).
    • !1473: chore: add ContextItemContentFetcher pre-processor (Pre-processor for fetching content).
    • !1474: refactor: add pre-processor pipeline ordering (Ordering for pre-processor pipeline).
    • !1483: refactor: migrate ContextRanker to pre-processor pipeline (Integrating ContextRanker).
  • Feature Flag Integration & API Interaction:
    • !1327: feat: introduce code suggestion context availability checking (Fetching feature flag status from Rails GraphQL).
    • !1365: refactor: fetch duo features in one graphql query (Refining GraphQL query for feature flags).
    • !1422: feat: enable ImportContextProvider via Feature Flag (Gating the provider).
  • Telemetry:
    • !1411: feat: add resolution_strategies to code suggestions telemetry (Updating telemetry for multiple context sources).
  • Bug Fixes/Follow-ups (example):
    • !1385: (MR that led to discovery of file URI inconsistency, addressed in issue gitlab-org/editor-extensions/gitlab-lsp#820).

GitLab Rails Application (gitlab-org/gitlab):

  • Feature Flag Management:
    • !187456: Enable FF code_suggestions_include_context_imports by default (Enabling the feature flag globally).
    • (Note: An earlier MR, likely gitlab-org/gitlab!178062 or gitlab-org/gitlab!177906 as per diffs, would have introduced the FF definition initially disabled. gitlab-org/gitlab!184060 is also cited in Report 11 as handling backend integration for FF checks and API for Imports Context).
  • Documentation:
    • !184060: Update Duo context awareness / Add imports context to code suggestions (Updates documentation to include imports context. Report 11 suggests this MR also handled backend integration for FF checks and API).
    • !184063: Add imports context to Code Suggestions docs (Adds a new section specifically for imports context).

Telemetry Schemas (gitlab-org/iglu):

  • !133: feat: add resolution_strategies to code suggestions telemetry fields (Updating Snowplow schema for code_suggestions_context).

Data Analytics (gitlab-data/analytics):

  • !11618: PDI2509: Add resolution_strategy downstream (Updating dbt models for analytics).
  • !11867: Resolve "Resolution Strategies" (Further updates to dbt models for resolution_strategies).

Marketing & Release Information (gitlab-com/www-gitlab-com):

  • !138888: Release Post: Duo Code Suggestions Imports Context (Announcing the feature).

3. What parts of the codebase did they change?

The implementation of the Imports Context Provider touched several areas across different GitLab projects:

A. gitlab-org/editor-extensions/gitlab-lsp (GitLab Language Server)

This project saw the most significant changes, as it houses the core logic for the feature.

  • AI Context Management (src/common/ai_context_management/):
    • New Provider: src/common/ai_context_management/context_providers/imports/import_context_provider.ts (and related files for import handlers, resolvers like javascript_import_resolver.ts, ts_config_store.ts).
    • Core Manager: ai_context_manager.ts was updated to integrate the new provider and manage a refactored context processing pipeline.
    • Pre-processors: New pre-processors were added or modified in src/common/ai_context_management/pre_processors/ for filtering, ranking (context_ranker.ts), and content fetching (context_item_content_fetcher.ts).
    • Diagram (from gitlab-lsp!1311 description, illustrating architecture): 
      classDiagram
    direction TB

    class AIContextManager {
        +getContext(IDocContext)
        +getContextForCodeSuggestions(CodeSuggestionsAIRequest)
    }

    class DefaultImportContextProvider {
        -logger: Logger
        -fsClient: FsClient
        -importHandlers: AbstractImportHandler[]
        -projectAccessChecker: DuoProjectAccessChecker
        -policy: FilePolicyProvider
        -openTabsService: OpenTabsService
        +getContextForCodeSuggestions(request: CodeSuggestionsAIRequest)
    }

    class AbstractImportHandler {
        <<Interface>>
    }

    DefaultImportContextProvider --|> AIContextProvider
    DefaultImportContextProvider o-- "*" AbstractImportHandler
    AIContextManager o-- "*" AIContextProvider
      (Note: Diagram slightly augmented based on typical class relations and information from reports.)
    • Diagram (Pre-Processor Flow from gitlab-lsp!1474 and !1483 descriptions): 
      flowchart TD
    A[DefaultSuggestionService gets context items] --> B[Create PreProcessorItems]
    B --> C[Run PreProcessorPipeline]

    subgraph Pipeline
        C --> D["1. DisabledItemPreProcessor
        Filter out disabled items"]
        D --> E["2. SupportedLanguagePreProcessor
        Filter by language support"]
        E --> F["3. ContextRanker
        Rank items by relevance"]
        F --> G["4. ContextItemContentFetcher
        Fetch content for each item"]
        G --> H["5. EmptyContentPreProcessor
        Filter out empty content"]
    end
  • Import Handling & Resolution (src/common/import_handling/, src/common/ai_context_management/context_providers/imports/ast/):
    • Logic for parsing import statements (AST analysis).
    • Resolution of different import path types (relative, non-relative, node_modules, workspace aliases).
    • Integration of enhanced-resolve dependency for advanced resolution.
    • Support for tsconfig.json and jsconfig.json to guide resolution.
  • Suggestion Service (src/common/suggestion/suggestion_service.ts):
    • Updated to utilize the new AI Context Management pipeline and the ImportContextProvider.
  • Feature Flag & Duo Access (src/common/services/duo_access/duo_feature_access_service.ts):
    • Logic to query the Rails GraphQL API for the code_suggestions_include_context_imports feature flag status.
  • Telemetry (src/common/tracking/code_suggestions/code_suggestions_snowplow_tracker.ts):
    • Updated to include the new resolution_strategies field in telemetry events, indicating when "imports" context was used.
  • Repository & File System Services (src/services/git/repository.ts, src/services/fs/fs_client.ts):
    • Modifications to track file changes for caching and to provide file system access for the resolution logic (especially in WebIDE).
  • Dependencies (package.json):
    • Added enhanced-resolve.
    • Moved typescript from a devDependency to a regular dependency (for tsconfig.json parsing).

B. gitlab-org/gitlab (Main Rails Application)

Changes in the Rails application were primarily focused on feature flag management, exposing flag status via API, and documentation.

  • Feature Flags:

    • Definition and management of the code_suggestions_include_context_imports feature flag.
    • File: config/feature_flags/development/code_suggestions_include_context_imports.yml (path may vary slightly based on FF type, e.g., ee/config/feature_flags/beta/).
    • Diff from gitlab-org/gitlab!187456 (enabling FF by default): 
      --- a/config/feature_flags/development/code_suggestions_include_context_imports.yml
+++ b/config/feature_flags/development/code_suggestions_include_context_imports.yml
@@ -1,5 +1,5 @@
 name: code_suggestions_include_context_imports
-introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177906
+introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/187456
 milestone: '16.10' # Note: Report 3 shows 17.0, Report 6 shows 17.0 for rollout_issue. This might be initial introduction milestone.
 type: development
 group: '@gitlab-org/modelops/applied-ml/code-suggestions'
@@ -7,3 +7,4 @@
 default_enabled: false
 percentage_of_users:
 percentage_of_groups:
+default_enabled: true
      (Note: The introduced_by_mr and milestone might vary slightly across reports if they refer to different stages of the FF lifecycle, e.g., initial definition vs. default enablement. The key change is default_enabled: true.) Report 6 also shows a change from type: beta to type: released for this FF in ee/config/feature_flags/beta/code_suggestions_include_context_imports.yml in MR !187456.

  • GraphQL API:

    • Exposing the availability of code suggestions contexts (including imports) via the GraphQL API for the Language Server to consume. This allows gitlab-lsp to check if the code_suggestions_include_context_imports feature is enabled for the user.
    • Likely changes in GraphQL type definitions (e.g., app/graphql/types/ai/code_suggestions/context_feature_type.rb) and resolvers (e.g., app/graphql/resolvers/ai/code_suggestions/features_resolver.rb or similar for currentUser).
    • GraphQL Query (from gitlab-org/gitlab#512976 description, used by LSP): 
      # query
query {
  currentUser {
    duoCodeSuggestionsAvailableFeatures # Field name might be slightly different, e.g. codeSuggestionsContexts
  }
}

# result
{
  "data": {
    "currentUser": {
      "duoCodeSuggestionsAvailableFeatures": [
        "include_imports_context",
      ]
    }
  }
}
      (Report 11 suggests MR gitlab-org/gitlab!184060 handled this backend integration.)

  • Documentation (doc/user/project/repository/code_suggestions/_index.md):

    • Updates to user documentation to describe the new "imports context" source.
    • Diff from gitlab-org/gitlab!184063 (adding new section): 
      --- a/doc/user/project/repository/code_suggestions/_index.md
+++ b/doc/user/project/repository/code_suggestions/_index.md
@@ -35,6 +35,23 @@
 Code Suggestions also uses files from your repository as context to make suggestions and generate code:
 *   Files open in other tabs in your IDE.
 *   Files identified by [Repository X-Ray](../repository_x_ray.md).
+*   Files imported by the file open in your IDE.
+
+### Imports context
+
+Code Suggestions uses the content of files imported by the file open in your IDE as context. This helps Code Suggestions understand the dependencies and structure of your code, leading to more accurate and relevant suggestions.
+
+For example, if you are working on a JavaScript file that imports a function from another file in your project, Code Suggestions can use the content of the imported file to provide suggestions related to that function.
+
+Imports context is available for the following languages:
+
+*   JavaScript
+*   TypeScript
+
+Imports context is enabled by default. To disable it, turn off the `code_suggestions_include_context_imports` feature flag.
+
+NOTE:
+Imports context is not available for all languages. Support for additional languages is planned for future iterations.
    • Diff from gitlab-org/gitlab!184060 (revising existing context list): 
      --- a/doc/user/project/repository/code_suggestions/_index.md
+++ b/doc/user/project/repository/code_suggestions/_index.md
@@ -31,21 +31,13 @@
 Code Suggestions is aware of and uses:

 *   The file open in your IDE.
-*   The content before and after the cursor in that file.
-*   The filename and extension.
-
-Code Suggestions also uses files from your repository as context to make suggestions and generate code:
-
-*   **Open tabs:** Code Suggestions uses content from other files you have open in your IDE.
-*   **Repository X-Ray:** Code Suggestions uses content from other files in your repository that are relevant to the file you are currently working in. This feature is automatically enabled and does not require any configuration.
-
-Code Suggestions does **not** use:
-
-*   Any files or content that are not part of your project repository.
-*   Any files or content that are not open in your IDE, unless Repository X-Ray is enabled.
-*   Any files or content that are excluded by your `.gitignore` file.
-*   Any files or content that are excluded by your `.ai-context-policy.json` file.
+*   The content before and after the cursor in that file, including the filename and extension.

+Code Suggestions can also use files from your repository as context to make suggestions and generate code:
+
+*   **Open tabs:** Code Suggestions uses content from other files you have open in your IDE.
+*   **Imported files:** Code Suggestions uses content from files imported in the file you are currently working in.
+*   **Repository X-Ray:** Code Suggestions uses content from other files in your repository that are relevant to the file you are currently working in. This feature is automatically enabled and does not require any configuration.

 Code Suggestions does **not** use:

C. gitlab-data/analytics (Data Warehouse)

Changes in this project relate to processing the new telemetry data for analysis and reporting.

  • dbt Models (transform/snowflake-dbt/models/):
    • Modifications to dbt models (e.g., fct_behavior_structured_event_code_suggestion.sql, rpt_behavior_code_suggestion_outcome.sql) to ingest, process, and include the resolution_strategies field from Snowplow events. This allows analysts to segment Code Suggestions data by the context source used (including "imports").
    • Files modified by gitlab-data/analytics!11618 and !11867 include:
      • transform/snowflake-dbt/macros/common/macro_prep_snowplow_unnested_events_all.sql
      • transform/snowflake-dbt/models/common/facts_sales_and_marketing/fct_behavior_structured_event_code_suggestion.sql
      • transform/snowflake-dbt/models/common_mart/mart_behavior_structured_event_code_suggestion.sql
      • transform/snowflake-dbt/models/common_mart_product/reports/rpt_behavior_code_suggestion_outcome.sql
      • And various schema (.yml, .md) files.

D. gitlab-org/iglu (Snowplow Schemas)

This project was updated to define the new structure for the telemetry data.

  • Snowplow Schemas (public/schemas/com.gitlab/code_suggestions_context/jsonschema/):
    • A new version of the code_suggestions_context schema (e.g., 3-7-0) was introduced to include the resolution_strategies field (as an array) within each context_items entry and a summary field context_items_resolution_strategies_summary.
    • Diff from gitlab-org/iglu!133 (schema 3-6-0 to 3-7-0): 
      --- a/public/schemas/com.gitlab/code_suggestions_context/jsonschema/3-6-0
+++ b/public/schemas/com.gitlab/code_suggestions_context/jsonschema/3-7-0
@@ -4,7 +4,7 @@
   "self": {
     "vendor": "com.gitlab",
     "name": "code_suggestions_context",
-    "version": "3-6-0",
+    "version": "3-7-0",
     "format": "jsonschema"
   },
   "type": "object",
@@ -155,10 +155,14 @@
             "description": "Type of the context item",
             "maxLength": 64
           },
-          "resolution_strategy": {
-            "description": "How the context item was resolved (e.g. open_tabs)",
-            "type": ["string", "null"],
-            "maxLength": 64
+          "resolution_strategies": {
+            "description": "How the context item was resolved (e.g. open_tabs, imports)",
+            "type": ["array", "null"],
+            "items": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "minItems": 1
           },
           "byte_size": {
             "description": "Size of the context item in bytes",
@@ -177,6 +181,15 @@
         "type": ["string", "null"],
         "maxLength": 255
       }
+            },
+            "required": [
+              "type",
+              "resolution_strategies",
+              "byte_size"
+            ]
+          },
+          "description": "List of context items used for the suggestion",
+          "type": ["array", "null"]
     },
     "context_items_byte_size": {
       "description": "Total size of all context items in bytes",
@@ -184,6 +197,13 @@
       "minimum": 0
     },
     "context_items_count": 
+      "description": "Total count of context items used for the suggestion",
+      "type": ["integer", "null"],
+      "minimum": 0
+    },
+    "context_items_resolution_strategies_summary": {
+      "description": "Summary list of all resolution strategies for the context items in one request",
+      "type": ["array", "null"],
       "description": "Total count of context items used for the suggestion",
       "type": ["integer", "null"],
       "minimum": 0

E. gitlab-com/www-gitlab-com (Marketing Website)

Updates to the release post to announce the feature.

  • data/release_posts/unreleased/: New files or modifications within this directory for the relevant release post item (e.g., gitlab-com/www-gitlab-com!138888).

4. Any Rails code changes?

Yes, there were specific changes to the GitLab Rails codebase (gitlab-org/gitlab), although the core logic for the Imports Context Provider itself resides in the gitlab-org/editor-extensions/gitlab-lsp project (TypeScript).

The Rails code changes were primarily for:

  1. Feature Flag Management:

    • Defining the code_suggestions_include_context_imports feature flag (e.g., in config/feature_flags/development/code_suggestions_include_context_imports.yml or similar).
    • Managing its rollout and enabling it by default (e.g., MR gitlab-org/gitlab!187456).

  2. GraphQL API Modifications:

    • Updating the GraphQL API to expose the status of the code_suggestions_include_context_imports feature flag (and potentially other context-related flags) to the Language Server (gitlab-lsp). This allows gitlab-lsp to dynamically enable or disable the Imports Context Provider based on the user's entitlements and feature flag settings.
    • This involved changes to GraphQL type definitions and resolvers, likely related to the currentUser query or a dedicated Duo/Code Suggestions feature query. Report 11 suggests MR gitlab-org/gitlab!184060 handled this backend integration.

  3. Documentation Updates:

    • Modifying user documentation files (primarily doc/user/project/repository/code_suggestions/_index.md) to inform users about the new "imports context" source and how it enhances Code Suggestions. This was done via MRs like gitlab-org/gitlab!184060 and gitlab-org/gitlab!184063.

No core feature logic (like AST parsing, import resolution, or context ranking for imports) was implemented in Ruby within the Rails application. The Rails application's role was to provide the necessary backend support (feature flagging, API for flag status) and user-facing information (documentation) for the feature implemented in the Language Server.

Relevant Comments from Issues/MRs:

5. Conclusion

The "Imports Context Provider" epic (gitlab-org/editor-extensions&58) represents a significant enhancement to GitLab Duo Code Suggestions, aiming to improve suggestion quality by incorporating context from imported files. The core implementation of this feature, including import analysis, path resolution, and context management, resides within the gitlab-org/editor-extensions/gitlab-lsp (Language Server) project. The gitlab-org/gitlab (Rails) application supported this epic through feature flag management, GraphQL API updates to expose feature availability, and crucial documentation updates. Telemetry systems (gitlab-org/iglu and gitlab-data/analytics) were also updated to track and analyze the impact of this new context source. The feature was rolled out progressively, controlled by the code_suggestions_include_context_imports feature flag, and is now enabled by default.

Edited by Michael Angelo Rivera