Edit: Faster doc workflow with more target context (#1900)

closes #1464

## Description

This PR:
- Streamlines the `doc` intent flow for fixup tasks. Previously we would
treat these as "edit", which means we would try to fetch lots of context
from the selected code. That is very rarely helpful, for documenting we
really just want to take the surrounding code and the current selection.

I also investigating going the other way, and fetching relevant
reference code for a documentable symbol. This confirmed to me that it's
not necessarily helpful. It can lead to the LLM documenting code based
on how it is used elsewhere rather than how it should be used. That
might help for "explaining" code but not for documenting. (Related PR:
#1904)


## Test plan

1. Run doc command via right click menu
2. Run doc command via sidebar
3. Run doc command via code action

<!-- Required. See
https://docs.sourcegraph.com/dev/background-information/testing_principles.
-->

lib/shared/src/chat/prompts/cody.json

@@ -5,7 +5,6 @@
       "prompt": "Write a brief documentation comment for the selected code. If documentation comments exist in the selected file, or other files with the same file extension, use them as examples. Pay attention to the scope of the selected code (e.g. exported function/API vs implementation detail in a function), and use the idiomatic style for that type of code scope. Only generate the documentation for the selected code, do not generate the code. Do not output any other code or comments besides the documentation. Output only the comment and do not enclose it in markdown.",
       "context": {
         "currentFile": true,
-        "currentDir": true,
         "selection": true
       },
       "mode": "insert"

lib/shared/src/chat/recipes/fixup.ts

@@ -1,5 +1,5 @@
 import { ContextMessage, getContextMessageWithResponse } from '../../codebase-context/messages'
-import { VsCodeFixupTaskRecipeData } from '../../editor'
+import { FixupIntent, VsCodeFixupTaskRecipeData } from '../../editor'
 import { MAX_CURRENT_FILE_TOKENS, MAX_HUMAN_INPUT_TOKENS } from '../../prompt/constants'
 import { populateCodeContextTemplate, populateCurrentEditorDiagnosticsTemplate } from '../../prompt/templates'
 import { truncateText, truncateTextStart } from '../../prompt/truncation'
@@ -9,12 +9,6 @@ import { Interaction } from '../transcript/interaction'
 import { getContextMessagesFromSelection } from './helpers'
 import { Recipe, RecipeContext, RecipeID } from './recipe'
 
-/**
- * The intent classification.
- * Inferred from the prefix provided to the fixup command, e.g. `/edit` or `/fix`
- */
-export type FixupIntent = 'add' | 'edit' | 'fix'
-
 export const PROMPT_TOPICS = {
     OUTPUT: 'CODE5711',
     SELECTED: 'SELECTEDCODE7662',
@@ -57,6 +51,7 @@ export class Fixup implements Recipe {
             case 'add':
                 return Fixup.addPrompt.replace('{instruction}', task.instruction).replace('{fileName}', task.fileName)
             case 'edit':
+            case 'doc':
                 return Fixup.editPrompt
                     .replace('{instruction}', promptInstruction)
                     .replace('{selectedText}', task.selectedText)
@@ -105,6 +100,11 @@ export class Fixup implements Recipe {
              * No additional context is required. We already have the errors directly via the instruction, and we know their selected code.
              */
             case 'fix':
+            /**
+             * Very narrow set of possible instructions.
+             * Fetching context is unlikely to be very helpful or optimal.
+             */
+            case 'doc': {
                 const contextMessages = []
                 if (truncatedPrecedingText.trim().length > 0) {
                     contextMessages.push(
@@ -123,6 +123,7 @@ export class Fixup implements Recipe {
                     )
                 }
                 return contextMessages
+            }
             /**
              * Broad set of possible instructions.
              * Fetch context from the users' selection, use any errors/warnings in said selection, and use context from current file.

lib/shared/src/editor/index.ts

@@ -68,7 +68,7 @@ export interface VsCodeInlineController {
  * The intent classification for the fixup.
  * Manually determined depending on how the fixup is triggered.
  */
-export type FixupIntent = 'add' | 'edit' | 'fix'
+export type FixupIntent = 'add' | 'edit' | 'fix' | 'doc'
 
 export interface VsCodeFixupTaskRecipeData {
     instruction: string

vscode/CHANGELOG.md

@@ -11,6 +11,7 @@ Starting from `0.2.0`, Cody is using `major.EVEN_NUMBER.patch` for release versi
 - Chat: New chat preview models `claude-2.1` is now avaliable for sourcegraph.com users. [pull/1860](https://github.com/sourcegraph/cody/pull/1860)
 - Edit: Added context-aware code actions for "Generate", "Edit" and "Document" commands. [pull/1724](https://github.com/sourcegraph/cody/pull/1724)
 - Chat: @'ing files now uses a case insensitive fuzzy search. [pull/1889](https://github.com/sourcegraph/cody/pull/1889)
+- Edit: Added a faster, more optimized response for the "document" command. [pull/1900](https://github.com/sourcegraph/cody/pull/1900)
 
 ### Fixed
 

vscode/src/code-actions/document.ts

@@ -1,5 +1,7 @@
 import * as vscode from 'vscode'
 
+import { FixupIntent } from '@sourcegraph/cody-shared/src/editor'
+
 import { execQueryWrapper } from '../tree-sitter/query-sdk'
 
 export class DocumentCodeAction implements vscode.CodeActionProvider {
@@ -33,7 +35,16 @@ export class DocumentCodeAction implements vscode.CodeActionProvider {
         const source = 'code-action:document'
         action.command = {
             command: 'cody.command.edit-code',
-            arguments: [{ instruction: this.instruction, range, intent: 'edit', document, insertMode: true }, source],
+            arguments: [
+                {
+                    instruction: this.instruction,
+                    range,
+                    intent: 'doc' satisfies FixupIntent,
+                    document,
+                    insertMode: true,
+                },
+                source,
+            ],
             title: displayText,
         }
         return action

vscode/src/code-actions/edit.ts

@@ -1,5 +1,7 @@
 import * as vscode from 'vscode'
 
+import { FixupIntent } from '@sourcegraph/cody-shared/src/editor'
+
 export class EditCodeAction implements vscode.CodeActionProvider {
     public static readonly providedCodeActionKinds = [vscode.CodeActionKind.RefactorRewrite]
 
@@ -36,7 +38,7 @@ export class EditCodeAction implements vscode.CodeActionProvider {
             arguments: [
                 {
                     range: selection ? new vscode.Range(selection.start, selection.end) : undefined,
-                    intent: 'edit',
+                    intent: 'edit' satisfies FixupIntent,
                     document,
                 },
                 source,

vscode/src/code-actions/fixup.ts

@@ -1,6 +1,6 @@
 import * as vscode from 'vscode'
 
-import { FixupIntent } from '@sourcegraph/cody-shared/src/chat/recipes/fixup'
+import { FixupIntent } from '@sourcegraph/cody-shared/src/editor'
 
 import { getSmartSelection } from '../editor/utils'
 

vscode/src/commands/CommandRunner.ts

@@ -1,6 +1,7 @@
 import * as vscode from 'vscode'
 
 import { CodyPrompt } from '@sourcegraph/cody-shared'
+import { FixupIntent } from '@sourcegraph/cody-shared/src/editor'
 
 import { getActiveEditor } from '../editor/active-editor'
 import { getSmartSelection } from '../editor/utils'
@@ -139,6 +140,7 @@ export class CommandRunner implements vscode.Disposable {
         }
 
         const range = this.kind === 'doc' ? getDocCommandRange(this.editor, selection, doc.languageId) : selection
+        const intent: FixupIntent = this.kind === 'doc' ? 'doc' : 'edit'
         const instruction = insertMode ? addSelectionToPrompt(this.command.prompt, code) : this.command.prompt
         const source = this.kind
         await vscode.commands.executeCommand(
@@ -147,6 +149,7 @@ export class CommandRunner implements vscode.Disposable {
                 range,
                 instruction,
                 document: doc,
+                intent,
                 auto: true,
                 insertMode,
             },

vscode/src/non-stop/FixupController.ts

@@ -1,8 +1,7 @@
 import * as vscode from 'vscode'
 
-import { FixupIntent } from '@sourcegraph/cody-shared/src/chat/recipes/fixup'
 import { ChatEventSource } from '@sourcegraph/cody-shared/src/chat/transcript/messages'
-import { VsCodeFixupController, VsCodeFixupTaskRecipeData } from '@sourcegraph/cody-shared/src/editor'
+import { FixupIntent, VsCodeFixupController, VsCodeFixupTaskRecipeData } from '@sourcegraph/cody-shared/src/editor'
 import { MAX_CURRENT_FILE_TOKENS } from '@sourcegraph/cody-shared/src/prompt/constants'
 import { truncateText } from '@sourcegraph/cody-shared/src/prompt/truncation'
 
@@ -624,8 +623,8 @@ export class FixupController
             return undefined
         }
 
-        // Expand the selection range for edits and fixes
-        const getSmartSelection = task.intent === 'edit' || task.intent === 'fix'
+        // Support expanding the selection range for intents where it is useful
+        const getSmartSelection = task.intent !== 'add'
         if (getSmartSelection && task.selectionRange) {
             const newRange = await this.getFixupTaskSmartSelection(task, task.selectionRange)
             task.selectionRange = newRange