docstrings and type errors

Author: Artmann

src/notebooks/deepnote/MimeTypeProcessor.ts

@@ -62,7 +62,7 @@ export class ImageMimeProcessor implements MimeProcessor {
                 return null;
             }
 
-            return NotebookCellOutputItem.binary(uint8Array, mimeType);
+            return new NotebookCellOutputItem(uint8Array, mimeType);
         } catch {
             return NotebookCellOutputItem.text(String(content), mimeType);
         }

src/notebooks/deepnote/deepnoteActivationService.ts

@@ -7,13 +7,21 @@ import type { DeepnoteProject, DeepnoteNotebook } from './deepnoteTypes';
 import { DeepnoteNotebookSelector } from './deepnoteNotebookSelector';
 import { Commands } from '../../platform/common/constants';
 
+/**
+ * Service responsible for activating and configuring Deepnote notebook support in VS Code.
+ * Registers serializers, command handlers, and manages the notebook selection workflow.
+ */
 @injectable()
 export class DeepnoteActivationService implements IExtensionSyncActivationService {
     private serializer: DeepnoteNotebookSerializer;
     private selector: DeepnoteNotebookSelector;
 
     constructor(@inject(IExtensionContext) private extensionContext: IExtensionContext) {}
 
+    /**
+     * Activates Deepnote support by registering serializers and commands.
+     * Called during extension activation to set up Deepnote integration.
+     */
     public activate() {
         this.serializer = new DeepnoteNotebookSerializer();
         this.selector = new DeepnoteNotebookSelector();

src/notebooks/deepnote/deepnoteDataConverter.ts

@@ -7,27 +7,44 @@ import { ErrorOutputHandler } from './outputHandlers/ErrorOutputHandler';
 import { RichOutputHandler } from './outputHandlers/RichOutputHandler';
 import { mergeMetadata, hasMetadataContent, generateBlockId, generateSortingKey } from './dataConversionUtils';
 
+/**
+ * Utility class for converting between Deepnote block structures and VS Code notebook cells.
+ * Handles bidirectional conversion while preserving metadata and execution state.
+ */
 export class DeepnoteDataConverter {
     private readonly outputDetector = new OutputTypeDetector();
     private readonly streamHandler = new StreamOutputHandler();
     private readonly errorHandler = new ErrorOutputHandler();
     private readonly richHandler = new RichOutputHandler();
+
+    /**
+     * Converts Deepnote blocks to VS Code notebook cells.
+     * Sorts blocks by sortingKey before conversion to maintain proper order.
+     * @param blocks Array of Deepnote blocks to convert
+     * @returns Array of VS Code notebook cell data
+     */
     convertBlocksToCells(blocks: DeepnoteBlock[]): NotebookCellData[] {
         return blocks
             .sort((a, b) => a.sortingKey.localeCompare(b.sortingKey))
             .map((block) => this.convertBlockToCell(block));
     }
 
+    /**
+     * Converts VS Code notebook cells back to Deepnote blocks.
+     * Generates missing IDs and sorting keys as needed.
+     * @param cells Array of VS Code notebook cells to convert
+     * @returns Array of Deepnote blocks
+     */
     convertCellsToBlocks(cells: NotebookCellData[]): DeepnoteBlock[] {
         return cells.map((cell, index) => this.convertCellToBlock(cell, index));
     }
 
     private convertBlockToCell(block: DeepnoteBlock): NotebookCellData {
         const cellKind = block.type === 'code' ? NotebookCellKind.Code : NotebookCellKind.Markup;
         const languageId = block.type === 'code' ? 'python' : 'markdown';
-        
+
         const cell = new NotebookCellData(cellKind, block.content, languageId);
-        
+
         cell.metadata = {
             deepnoteBlockId: block.id,
             deepnoteBlockType: block.type,
@@ -36,9 +53,9 @@ export class DeepnoteDataConverter {
             ...(typeof block.executionCount === 'number' && { executionCount: block.executionCount }),
             ...(block.outputReference && { deepnoteOutputReference: block.outputReference })
         };
-        
+
         cell.outputs = this.convertDeepnoteOutputsToVSCodeOutputs(block.outputs || []);
-        
+
         return cell;
     }
 
@@ -79,7 +96,7 @@ export class DeepnoteDataConverter {
 
     private convertSingleOutput(output: DeepnoteOutput): NotebookCellOutput {
         const outputItems = this.createOutputItems(output);
-        
+
         const metadata = mergeMetadata(
             output.metadata,
             output.execution_count !== undefined ? { executionCount: output.execution_count } : undefined
@@ -101,7 +118,7 @@ export class DeepnoteDataConverter {
 
         switch (detection.type) {
             case 'error':
-                deepnoteOutput = this.errorHandler.convertToDeepnote(output, detection.errorItem!);
+                deepnoteOutput = this.errorHandler.convertToDeepnote(detection.errorItem!);
                 break;
             case 'stream':
                 deepnoteOutput = this.streamHandler.convertToDeepnote(output);
@@ -115,7 +132,7 @@ export class DeepnoteDataConverter {
         // Preserve metadata from VS Code output
         if (output.metadata) {
             deepnoteOutput.metadata = mergeMetadata(deepnoteOutput.metadata, output.metadata);
-            
+
             // Extract execution count from metadata
             if (output.metadata.executionCount !== undefined) {
                 deepnoteOutput.execution_count = output.metadata.executionCount as number;
@@ -125,7 +142,6 @@ export class DeepnoteDataConverter {
         return deepnoteOutput;
     }
 
-
     private createOutputItems(output: DeepnoteOutput): NotebookCellOutputItem[] {
         switch (output.output_type) {
             case 'stream':
@@ -143,5 +159,4 @@ export class DeepnoteDataConverter {
                 return [];
         }
     }
-
 }

src/notebooks/deepnote/deepnoteNotebookManager.ts

@@ -1,19 +1,38 @@
 import type { DeepnoteProject } from './deepnoteTypes';
 
+/**
+ * Centralized manager for tracking Deepnote notebook selections and project state.
+ * Manages per-project and per-URI state including current selections and user preferences.
+ */
 export class DeepnoteNotebookManager {
     private currentNotebookId = new Map<string, string>();
     private originalProjects = new Map<string, DeepnoteProject>();
     private selectedNotebookByUri = new Map<string, string>();
     private skipPromptForUri = new Set<string>();
 
+    /**
+     * Gets the currently selected notebook ID for a project.
+     * @param projectId Project identifier
+     * @returns Current notebook ID or undefined if not set
+     */
     getCurrentNotebookId(projectId: string): string | undefined {
         return this.currentNotebookId.get(projectId);
     }
 
+    /**
+     * Retrieves the original project data for a given project ID.
+     * @param projectId Project identifier
+     * @returns Original project data or undefined if not found
+     */
     getOriginalProject(projectId: string): DeepnoteProject | undefined {
         return this.originalProjects.get(projectId);
     }
 
+    /**
+     * Gets the selected notebook ID for a specific file URI.
+     * @param uri File URI string
+     * @returns Selected notebook ID or undefined if not set
+     */
     getSelectedNotebookForUri(uri: string): string | undefined {
         return this.selectedNotebookByUri.get(uri);
     }
@@ -32,6 +51,12 @@ export class DeepnoteNotebookManager {
         this.skipPromptForUri.add(uri);
     }
 
+    /**
+     * Checks if prompts should be skipped for a given URI and consumes the skip flag.
+     * This is used to avoid showing selection prompts immediately after a user makes a choice.
+     * @param uri File URI string
+     * @returns True if prompts should be skipped (and resets the flag)
+     */
     shouldSkipPrompt(uri: string): boolean {
         if (this.skipPromptForUri.has(uri)) {
             this.skipPromptForUri.delete(uri);
@@ -42,11 +67,24 @@ export class DeepnoteNotebookManager {
         return false;
     }
 
+    /**
+     * Stores the original project data and sets the initial current notebook.
+     * This is used during deserialization to cache project data and track the active notebook.
+     * @param projectId Project identifier
+     * @param project Original project data to store
+     * @param notebookId Initial notebook ID to set as current
+     */
     storeOriginalProject(projectId: string, project: DeepnoteProject, notebookId: string): void {
         this.originalProjects.set(projectId, project);
         this.currentNotebookId.set(projectId, notebookId);
     }
 
+    /**
+     * Updates the current notebook ID for a project.
+     * Used when switching notebooks within the same project.
+     * @param projectId Project identifier
+     * @param notebookId New current notebook ID
+     */
     updateCurrentNotebookId(projectId: string, notebookId: string): void {
         this.currentNotebookId.set(projectId, notebookId);
     }

src/notebooks/deepnote/deepnoteNotebookSelector.ts

@@ -7,7 +7,18 @@ interface NotebookQuickPickItem extends QuickPickItem {
     notebook: DeepnoteNotebook;
 }
 
+/**
+ * Provides user interface for selecting notebooks within a Deepnote project.
+ * Creates and manages VS Code QuickPick interface for notebook selection.
+ */
 export class DeepnoteNotebookSelector {
+    /**
+     * Presents a notebook selection interface to the user.
+     * @param notebooks Available notebooks to choose from
+     * @param currentNotebookId Currently selected notebook ID for pre-selection
+     * @param options Optional configuration for the selection UI
+     * @returns Promise resolving to selected notebook or undefined if cancelled
+     */
     async selectNotebook(
         notebooks: DeepnoteNotebook[],
         currentNotebookId?: string,

src/notebooks/deepnote/deepnoteSerializer.ts

@@ -1,35 +1,64 @@
-import { type NotebookData, type NotebookSerializer, type CancellationToken } from 'vscode';
+import { type CancellationToken, type NotebookData, type NotebookSerializer } from 'vscode';
 import * as yaml from 'js-yaml';
-import { DeepnoteProject, DeepnoteNotebook } from './deepnoteTypes';
+import type { DeepnoteProject, DeepnoteNotebook } from './deepnoteTypes';
 import { DeepnoteNotebookManager } from './deepnoteNotebookManager';
 import { DeepnoteNotebookSelector } from './deepnoteNotebookSelector';
 import { DeepnoteDataConverter } from './deepnoteDataConverter';
 
 export { DeepnoteProject, DeepnoteNotebook, DeepnoteBlock, DeepnoteOutput } from './deepnoteTypes';
 
+/**
+ * Callback function type for handling notebook selection during deserialization.
+ * @param projectId Project identifier containing the notebooks
+ * @param notebooks Available notebooks to choose from
+ * @returns Promise resolving to selected notebook or undefined
+ */
 export type NotebookSelectionCallback = (
     projectId: string,
     notebooks: DeepnoteNotebook[]
 ) => Promise<DeepnoteNotebook | undefined>;
 
+/**
+ * Serializer for converting between Deepnote YAML files and VS Code notebook format.
+ * Handles reading/writing .deepnote files and manages project state persistence.
+ */
 export class DeepnoteNotebookSerializer implements NotebookSerializer {
     private manager = new DeepnoteNotebookManager();
     private selector = new DeepnoteNotebookSelector();
     private converter = new DeepnoteDataConverter();
     private notebookSelectionCallback?: NotebookSelectionCallback;
 
+    /**
+     * Gets the notebook manager instance for accessing project state.
+     * @returns DeepnoteNotebookManager instance
+     */
     getManager(): DeepnoteNotebookManager {
         return this.manager;
     }
 
+    /**
+     * Gets the data converter instance for cell/block conversion.
+     * @returns DeepnoteDataConverter instance
+     */
     getConverter(): DeepnoteDataConverter {
         return this.converter;
     }
 
+    /**
+     * Sets a custom callback for handling notebook selection during deserialization.
+     * @param callback Function to call when notebook selection is needed
+     */
     setNotebookSelectionCallback(callback: NotebookSelectionCallback) {
         this.notebookSelectionCallback = callback;
     }
 
+    /**
+     * Deserializes a Deepnote YAML file into VS Code notebook format.
+     * Parses YAML, selects appropriate notebook, and converts blocks to cells.
+     * @param content Raw file content as bytes
+     * @param _token Cancellation token (unused)
+     * @returns Promise resolving to notebook data
+     */
     async deserializeNotebook(content: Uint8Array, _token: CancellationToken): Promise<NotebookData> {
         try {
             const contentString = Buffer.from(content).toString('utf8');
@@ -71,6 +100,13 @@ export class DeepnoteNotebookSerializer implements NotebookSerializer {
         }
     }
 
+    /**
+     * Serializes VS Code notebook data back to Deepnote YAML format.
+     * Converts cells to blocks, updates project data, and generates YAML.
+     * @param data Notebook data to serialize
+     * @param _token Cancellation token (unused)
+     * @returns Promise resolving to YAML content as bytes
+     */
     async serializeNotebook(data: NotebookData, _token: CancellationToken): Promise<Uint8Array> {
         try {
             const projectId = data.metadata?.deepnoteProjectId;

src/notebooks/deepnote/deepnoteTypes.ts

@@ -1,6 +1,11 @@
+/**
+ * Represents a complete Deepnote project structure with metadata, notebooks, and settings.
+ */
 export interface DeepnoteProject {
     metadata: {
+        /** ISO timestamp when the project was created */
         createdAt: string;
+        /** ISO timestamp when the project was last modified */
         modifiedAt: string;
     };
     project: {
@@ -12,6 +17,9 @@ export interface DeepnoteProject {
     version: string;
 }
 
+/**
+ * Represents a single notebook within a Deepnote project.
+ */
 export interface DeepnoteNotebook {
     blocks: DeepnoteBlock[];
     executionMode: string;
@@ -21,6 +29,10 @@ export interface DeepnoteNotebook {
     workingDirectory?: string;
 }
 
+/**
+ * Represents a single block (cell) within a Deepnote notebook.
+ * Can be either a code block or a markdown block.
+ */
 export interface DeepnoteBlock {
     content: string;
     executionCount?: number;
@@ -32,11 +44,19 @@ export interface DeepnoteBlock {
     type: 'code' | 'markdown';
 }
 
+/**
+ * Represents output data generated by executing a code block.
+ */
 export interface DeepnoteOutput {
     data?: Record<string, unknown>;
+    ename?: string;
+    error?: unknown;
+    evalue?: string;
     execution_count?: number;
     metadata?: Record<string, unknown>;
     name?: string;
     output_type: string;
+    stack?: string;
     text?: string;
+    traceback?: string[];
 }

src/notebooks/deepnote/outputHandlers/ErrorOutputHandler.ts

@@ -1,4 +1,4 @@
-import { NotebookCellOutput, NotebookCellOutputItem, l10n } from 'vscode';
+import { NotebookCellOutputItem, l10n } from 'vscode';
 import { decodeContent, parseJsonSafely } from '../dataConversionUtils';
 import type { DeepnoteOutput } from '../deepnoteTypes';
 
@@ -9,7 +9,7 @@ export class ErrorOutputHandler {
     /**
      * Convert VS Code error output to Deepnote format
      */
-    convertToDeepnote(output: NotebookCellOutput, errorItem: { mime: string; data: Uint8Array }): DeepnoteOutput {
+    convertToDeepnote(errorItem: { mime: string; data: Uint8Array }): DeepnoteOutput {
         const deepnoteOutput: DeepnoteOutput = {
             output_type: 'error'
         };