Merge pull request #7493 from continuedev/jacob/con-3748

docs: add lots of comments

Author: RomneyDa

core/core.ts

@@ -668,6 +668,8 @@ export class Core {
       return queue.dequeueProcessed() || null;
     });
 
+    // NOTE: This is not used unless prefetch is used.
+    // At this point this is not used because I opted to rely on the model to return multiple diffs than to use prefetching.
     on("nextEdit/queue/processOne", async (msg) => {
       console.log("nextEdit/queue/processOne");
       const { ctx, recentlyVisitedRanges, recentlyEditedRanges } = msg.data;

core/nextEdit/NextEditEditableRegionCalculator.ts

@@ -13,6 +13,10 @@ export enum EditableRegionStrategy {
   Static = "static",
 }
 
+/**
+ * This was an attempt to find next edit locations deterministically.
+ * I was intending to use this in tandem with the prefetching logic, but we are not using it anymore.
+ */
 export async function getNextEditableRegion(
   strategy: EditableRegionStrategy,
   ctx: any,

core/nextEdit/NextEditPrefetchQueue.ts

@@ -10,6 +10,11 @@ export interface ProcessedItem {
 /**
  * Keeps a queue of the broken down diffs from a changed editable range, as determined in core/nextEdit/diff.ts
  */
+/**
+ * This is where the chain is stored. Think of it as a regular queue, but being a singleton because we need one source of truth for the chain.
+ * I originally intended this to be a separate data structure to handle prefetching next edit outcomes from the model in the background.
+ * Due to subpar results, lack of satisfactory next edit location suggestion algorithms and token cost/latency issues, I scratched the idea.
+ */
 export class PrefetchQueue {
   private static instance: PrefetchQueue | null = null;
 

core/nextEdit/NextEditProvider.ts

@@ -19,7 +19,6 @@ import { HelperVars } from "../autocomplete/util/HelperVars.js";
 import { AutocompleteInput } from "../autocomplete/util/types.js";
 import { isSecurityConcern } from "../indexing/ignore.js";
 import { modelSupportsNextEdit } from "../llm/autodetect.js";
-import { countTokens } from "../llm/countTokens.js";
 import { localPathOrUriToPath } from "../util/pathToUri.js";
 import { createDiff, DiffFormatType } from "./context/diffFormatting.js";
 import { DocumentHistoryTracker } from "./DocumentHistoryTracker.js";
@@ -45,6 +44,14 @@ const ERRORS_TO_IGNORE = [
   "operation was aborted",
 ];
 
+/**
+ * This is the next edit analogue to autocomplete's CompletionProvider.
+ * You will see a lot of similar if not identical methods to CompletionProvider methods.
+ * All logic used to live inside this class, but that became untenable quickly.
+ * I moved a lot of the model-specific logic (prompt building, pre/post processing, etc.) to the BaseNextEditProvider and the children inheriting from it.
+ * Keeping this class around might be a good idea because it handles lots of delicate logic such as abort signals, chains, logging, etc.
+ * There being a singleton also gives a lot of guarantees about the state of the next edit state machine.
+ */
 export class NextEditProvider {
   private static instance: NextEditProvider | null = null;
 
@@ -62,7 +69,6 @@ export class NextEditProvider {
   private currentEditChainId: string | null = null;
   private previousRequest: AutocompleteInput | null = null;
   private previousCompletions: NextEditOutcome[] = [];
-  // private nextEditableRegionsInTheCurrentChain: RangeInFile[] = [];
 
   // Model-specific provider instance.
   private modelProvider: BaseNextEditModelProvider | null = null;
@@ -223,14 +229,14 @@ export class NextEditProvider {
 
     this.currentEditChainId = null;
     this.previousCompletions = [];
-    // TODO: this should be cleaned up in the prefetch queue.
-    // this.nextEditableRegionsInTheCurrentChain = [];
 
     if (this.previousRequest) {
       const fileContent = (
         await this.ide.readFile(this.previousRequest.filepath)
       ).toString();
+
       const ast = await getAst(this.previousRequest.filepath, fileContent);
+
       if (ast) {
         DocumentHistoryTracker.getInstance().push(
           localPathOrUriToPath(this.previousRequest.filepath),
@@ -253,6 +259,9 @@ export class NextEditProvider {
     return this.previousCompletions.length === 1;
   }
 
+  /**
+   * This is the main entry point to this class.
+   */
   public async provideInlineCompletionItems(
     input: AutocompleteInput,
     token: AbortSignal | undefined,
@@ -370,6 +379,8 @@ export class NextEditProvider {
       throw new Error("Model provider not initialized");
     }
 
+    // NOTE: getAllSnippetsWithoutRace doesn't seem to incur much performance penalties when compared to getAllSnippets.
+    // Use getAllSnippets if snippet gathering becomes noticably slow.
     const [snippetPayload, workspaceDirs] = await Promise.all([
       getAllSnippetsWithoutRace({
         helper,
@@ -445,6 +456,9 @@ export class NextEditProvider {
     }
 
     // Send prompts to LLM (using only user prompt for fine-tuned models).
+    // prompts[1] extracts the user prompt from the system-user prompt pair.
+    // NOTE: Stream is currently set to false, but this should ideally be a per-model flag.
+    // Mercury Coder currently does not support streaming.
     const msg: ChatMessage = await llm.chat([prompts[1]], token, {
       stream: false,
     });
@@ -484,7 +498,7 @@ export class NextEditProvider {
     }
 
     if (outcome) {
-      // Handle NextEditProvider-specific state
+      // Handle NextEditProvider-specific state.
       this.previousCompletions.push(outcome);
 
       // Mark as displayed for JetBrains
@@ -494,97 +508,6 @@ export class NextEditProvider {
     return outcome;
   }
 
-  private _calculateOptimalEditableRegion(
-    helper: HelperVars,
-    heuristic: "fourChars" | "tokenizer" = "tokenizer",
-  ): {
-    editableRegionStartLine: number;
-    editableRegionEndLine: number;
-  } {
-    const cursorLine = helper.pos.line;
-    const fileLines = helper.fileLines;
-    const MAX_TOKENS = 512;
-
-    // Initialize with cursor line.
-    let editableRegionStartLine = cursorLine;
-    let editableRegionEndLine = cursorLine;
-
-    // Get initial content and token count.
-    let currentContent = fileLines[cursorLine];
-    let totalTokens =
-      heuristic === "tokenizer"
-        ? countTokens(currentContent, helper.modelName)
-        : Math.ceil(currentContent.length / 4);
-
-    // Expand outward alternating between adding lines above and below.
-    let addingAbove = true;
-
-    while (totalTokens < MAX_TOKENS) {
-      let addedLine = false;
-
-      if (addingAbove) {
-        // Try to add a line above.
-        if (editableRegionStartLine > 0) {
-          editableRegionStartLine--;
-          const lineContent = fileLines[editableRegionStartLine];
-          const lineTokens =
-            heuristic === "tokenizer"
-              ? countTokens(lineContent, helper.modelName)
-              : Math.ceil(lineContent.length / 4);
-
-          totalTokens += lineTokens;
-          addedLine = true;
-        }
-      } else {
-        // Try to add a line below.
-        if (editableRegionEndLine < fileLines.length - 1) {
-          editableRegionEndLine++;
-          const lineContent = fileLines[editableRegionEndLine];
-          const lineTokens =
-            heuristic === "tokenizer"
-              ? countTokens(lineContent, helper.modelName)
-              : Math.ceil(lineContent.length / 4);
-
-          totalTokens += lineTokens;
-          addedLine = true;
-        }
-      }
-
-      // If we can't add in the current direction, try the other.
-      if (!addedLine) {
-        // If we're already at both file boundaries, we're done.
-        if (
-          editableRegionStartLine === 0 &&
-          editableRegionEndLine === fileLines.length - 1
-        ) {
-          break;
-        }
-
-        // If we couldn't add in one direction, force the next attempt in the other direction.
-        addingAbove = !addingAbove;
-        continue;
-      }
-
-      // If we exceeded the token limit, revert the last addition.
-      if (totalTokens > MAX_TOKENS) {
-        if (addingAbove) {
-          editableRegionStartLine++;
-        } else {
-          editableRegionEndLine--;
-        }
-        break;
-      }
-
-      // Alternate between adding above and below for balanced context.
-      addingAbove = !addingAbove;
-    }
-
-    return {
-      editableRegionStartLine,
-      editableRegionEndLine,
-    };
-  }
-
   private async _markDisplayedIfJetBrains(
     completionId: string,
     outcome: NextEditOutcome,
@@ -595,6 +518,12 @@ export class NextEditProvider {
     }
   }
 
+  /**
+   * This is a wrapper around provideInlineCompletionItems.
+   * This is invoked when we call the model in the background using prefetch.
+   * It's not currently used anywhere (references are not used either), but I decided to keep it in case we actually need to use prefetch.
+   * You will see that calls to this method is made from NextEditPrefetchQueue.proecss(), which is wrapped in `if (!this.usingFullFileDiff)`.
+   */
   public async provideInlineCompletionItemsWithChain(
     ctx: {
       completionId: string;