devsplain 1.6.0 → 1.7.0

package/README.md

@@ -6,7 +6,7 @@ An industrial-grade, agent-agnostic CLI tool that automatically adds JSDoc and i
 
 ## Key Features
 
-- **Mathematical Safety Invariants**: Uses an index-preserving splicing engine. Your functional code is mathematically verified to remain identical before and after commenting.
+- **Deterministic Code Integrity Verification**: Uses an index-preserving splicing engine. Your non-comment source lines are guaranteed to remain byte-for-byte identical after comment insertion.
 - **Multi-Language support**: Natively parses JavaScript, JSX, TypeScript, TSX, HTML, CSS, SCSS, Vue, Svelte, Python, Java, C, C++, C#, Go, Ruby, PHP, Rust, Swift, Kotlin, Dart, and Shell scripts.
 - **Comment Preservation & Tagging**: AI-generated comments are tagged with `[ds]`. Your manually written comments are safe and will never be touched by the engine.
 - **Local Deterministic Scrubber**: The `--clean` flag strips AI-generated `[ds]` comments locally using a deterministic lexical state machine—no LLM calls, API keys, or internet required.
@@ -35,6 +35,19 @@ Many AI code formatters rewrite your code entirely, exposing you to logic regres
 ### String Literal Guardrails
 The engine tracks lexical state across template strings, single quotes, double quotes, and multi-line docstrings (such as Python triple-quotes). Comment insertion is blocked if the target line resides within a string literal, preventing broken syntax.
 
+### Why Not AST Verification?
+
+AST verification would require language-specific parser dependencies for every supported language.
+
+`devsplain` instead uses deterministic source-preservation verification:
+
+1. Original source is loaded.
+2. Comments are inserted.
+3. Generated comments are removed.
+4. The remaining source must match the original file exactly.
+
+If any non-comment source line differs, the operation aborts.
+
 ---
 
 ## Installation

package/bin/cli.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 let rl;
 let askQuestion;
 
-/** Checks if the current Git repository is dirty by inspecting status. */
+/** Checks if the current Git repository has uncommitted changes [ds] */
 function isGitDirty() {
     try {
         const gitDir = execSync('git rev-parse --is-inside-work-tree', { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim();
@@ -23,8 +23,7 @@ function isGitDirty() {
     return false;
 }
 
-/** Determines if a specific line index is within a string literal (handling quotes/backticks). [ds] */
-/** Determines if a specific line index is within a string literal (handling quotes/backticks). */
+/** Checks if a given line index is inside a string in a list of code lines [ds] */
 function isLineInsideString(lines, targetLineIndex, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     let inBacktick = false;
@@ -98,8 +97,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
 }
 
-/** Parses a file to identify pure comments and block structures. [ds] */
-/** Parses a file to identify pure comments and block structures. */
+/** Analyzes comments in a list of code lines [ds] */
 function analyzeComments(lines, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
@@ -135,12 +133,23 @@ function analyzeComments(lines, ext = '') {
                 j++;
                 continue;
             }
+            // Check for comment start index in non-Python files [ds]
             if (!inSingle && !inDouble && !inBacktick && !inTripleSingle && !inTripleDouble) {
                 if (isPython) {
                     if (line[j] === '#') {
                         commentStartIndex = j;
                         break;
                     }
+                    if (line.slice(j, j + 2) === '/*') {
+                        commentStartIndex = j;
+                        inBlockJS = true;
+                        j += 2;
+                        continue;
+                    }
+                    if (line.slice(j, j + 2) === '//') {
+                        commentStartIndex = j;
+                        break;
+                    }
                 } else if (isHTML) {
                     if (line.slice(j, j + 4) === '<!--') {
                         commentStartIndex = j;
@@ -148,6 +157,12 @@ function analyzeComments(lines, ext = '') {
                         j += 4;
                         continue;
                     }
+                    if (line.slice(j, j + 2) === '/*') {
+                        commentStartIndex = j;
+                        inBlockJS = true;
+                        j += 2;
+                        continue;
+                    }
                     if (line.slice(j, j + 2) === '//') {
                         commentStartIndex = j;
                         break;
@@ -184,6 +199,7 @@ function analyzeComments(lines, ext = '') {
                         continue;
                     }
                 }
+            // Check for string literals in non-Python files [ds]
             } else {
                 if (!inSingle && !inDouble) {
                     if (line[j] === '`') {
@@ -223,6 +239,7 @@ function analyzeComments(lines, ext = '') {
                     }
                 }
             }
+            // Increment character index [ds]
             j++;
         }
         if (!isPython) {
@@ -250,8 +267,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splices comments into code or cleans existing ones, with safety checks. [ds] */
-/** Splices comments into code or cleans existing ones, with safety checks. */
+/** Splices comments into a list of code lines [ds] */
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -266,7 +282,6 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     if (mode === 'clean' || mode === 'prune') {
         analysis = analyzeComments(originalLines, ext);
         const finalDeletions = new Set();
-        
         if (mode === 'clean') {
             let i = 0;
             while (i < originalLines.length) {
@@ -274,15 +289,12 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
                     let start = i;
                     let end = i;
                     while (end < originalLines.length && analysis[end].isInsideBlock) end++;
-                    
                     let blockStart = start - 1;
                     let blockEnd = end - 1;
-                    
                     let hasDs = false;
                     for (let k = blockStart; k <= blockEnd; k++) {
                         if (originalLines[k].includes('[ds]')) hasDs = true;
                     }
-                    
                     if (hasDs) {
                         for (let k = blockStart; k <= blockEnd; k++) {
                             dsBlocks.add(k + 1);
@@ -420,7 +432,6 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             if (lineAnalysis && lineAnalysis.commentStartIndex !== -1 && !lineAnalysis.isPureComment) {
                 const isDsBlockLine = dsBlocks.has(origIdx + 1);
                 const hasDsInline = originalLine.includes('[ds]');
-                
                 if (mode === 'prune' || (mode === 'clean' && (hasDsInline || isDsBlockLine))) {
                     const expectedStripped = originalLine.slice(0, lineAnalysis.commentStartIndex).trimEnd();
                     if (text === expectedStripped) {
@@ -448,8 +459,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Main entry point for the CLI tool. [ds] */
-/** Main entry point for the CLI tool. */
+/** Runs the CLI interface for the commenting tool [ds] */
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -504,7 +514,6 @@ Options:
         return;
     }
 
-    // Helper to extract flag values from command line arguments [ds]
     const getArgValue = (flag) => {
         const index = args.indexOf(flag);
         if (index !== -1 && index + 1 < args.length) {
@@ -570,9 +579,8 @@ Options:
     let successCount = 0;
     let failCount = 0;
 
-    /** Recursively processes files or directories to apply AI-generated comments. [ds] */
-    /** Recursively processes files or directories to apply AI-generated comments. */
     async function processPath(targetPath) {
+        // Process a directory or file path [ds]
         const stats = fs.statSync(targetPath);
 
         if (stats.isDirectory()) {
@@ -581,7 +589,8 @@ Options:
                 'node_modules', '.git', 'dist', 'build', 'out', 
                 '.next', '.nuxt', '.svelte-kit', 
                 'venv', 'env', '.venv',          
-                '.vscode', '.idea', 'coverage'   
+                '.vscode', '.idea', 'coverage',
+                'tests', '__tests__', 'fixtures'
             ];
 
             if (ignoredFolders.includes(folderName)) {
@@ -618,12 +627,12 @@ Options:
             try {
                 let comments = [];
                 let commentedCode;
-                if (mode !== 'clean') {
+                if (mode !== 'clean' && mode !== 'prune') {
                     const cleanData = spliceComments(data, [], 'clean', ext);
                     comments = await getComments(cleanData, filename, config, mode);
                     commentedCode = spliceComments(cleanData, comments, mode, ext);
                 } else {
-                    commentedCode = spliceComments(data, [], 'clean', ext);
+                    commentedCode = spliceComments(data, [], mode, ext);
                 }
                 if (isDryRun) {
                     console.log(`\n --- DRY RUN PREVIEW: ${filename} ---`);
@@ -668,8 +677,7 @@ Options:
     rl.close();
 }
 
-// Check if the script is run directly vs required as a module [ds]
-// Check if the script is run directly vs required as a module
+// Run the CLI interface if this script is the main module [ds]
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/bin/post-commit.js

@@ -3,45 +3,43 @@ const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
 
-/** Main execution block to detect changes and process documentation generation [ds] */
-/** Main execution block to detect changes and process documentation generation */
+/** Attempts to execute the post-commit hook [ds] */
 try {
-    // Prevent recursive loops if the previous commit was an automated documentation commit
-    // Retrieve the last commit message to prevent infinite loops during automated commits [ds]
+    // Get the last commit message [ds]
     const lastCommitMsg = execSync('git log -1 --format=%s', { encoding: 'utf8' }).trim();
     if (lastCommitMsg === 'docs: auto-generated comments by devsplain') {
         process.exit(0);
     }
 
-    // Get the list of file paths modified in the current commit [ds]
+    // Get the list of changed files in the last commit [ds]
     const changedFilesStr = execSync('git diff-tree --no-commit-id --name-only -r HEAD', { encoding: 'utf8' }).trim();
     if (!changedFilesStr) {
         process.exit(0);
     }
-    // Retrieve list of files modified in the latest commit
     const changedFiles = changedFilesStr.split(/\r?\n/);
 
-    // Define allowed file types for documentation processing [ds]
+    /** Defines a list of valid file extensions for commenting [ds] */
     const validExtensions = [
         '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
         '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs',
         '.swift', '.kt', '.dart', '.sh'
     ];
 
-    // Filter for supported file extensions and ensure the file still exists
+    /** Filters the changed files based on valid extensions and existence [ds] */
     const filesToComment = changedFiles.filter(file => {
         const ext = path.extname(file).toLowerCase();
-        return validExtensions.includes(ext) && fs.existsSync(file);
+        const isIgnored = file.includes('node_modules/') || file.includes('tests/') || file.includes('__tests__/') || file.includes('fixtures/');
+        return validExtensions.includes(ext) && fs.existsSync(file) && !isIgnored;
     });
 
     if (filesToComment.length === 0) {
         process.exit(0);
     }
 
+    // Log the number of files to be commented [ds]
     console.log(`[devsplain] Found ${filesToComment.length} file(s) in the last commit to auto-comment.`);
 
-    // Parse command line arguments to determine documentation verbosity mode
-    // Parse CLI arguments for verbosity preferences [ds]
+    // Parse command-line arguments for commenting mode [ds]
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
@@ -49,15 +47,13 @@ try {
 
     let commentedAny = false;
 
-    // Process each valid file to determine if documentation needs updating
+    /** Iterates through the files to be commented and attempts to comment each one [ds] */
     for (const file of filesToComment) {
         try {
             const ext = path.extname(file).toLowerCase();
             const contentHead = fs.readFileSync(file, 'utf8');
             let contentPrev = '';
             try {
-                // Attempt to retrieve the file version from the previous commit for change comparison [ds]
-                // Attempt to fetch the file content from the previous commit state for comparison
                 contentPrev = execSync(`git show HEAD~1:"${file}"`, { 
                     encoding: 'utf8', 
                     stdio: ['ignore', 'pipe', 'ignore'] 
@@ -65,12 +61,10 @@ try {
             } catch (prevErr) {
             }
 
+            // Check if the file has been modified beyond just comments [ds]
             if (contentPrev) {
-                // Prune comments to isolate actual code changes and ignore documentation-only commits [ds]
-                // Strip comments from head and previous versions to detect if logic actually changed
                 const cleanHead = spliceComments(contentHead, [], 'prune', ext);
                 const cleanPrev = spliceComments(contentPrev, [], 'prune', ext);
-                // Skip processing if only comments were modified in the commit
                 if (cleanHead === cleanPrev) {
                     console.log(`[devsplain] Skipping ${file}: commit contains only comment changes.`);
                     continue;
@@ -79,10 +73,9 @@ try {
         } catch (cleanErr) {
         }
 
+        // Attempt to comment the file using the cli script [ds]
         console.log(`[devsplain] Automatically commenting file: ${file}`);
         try {
-            // Execute the CLI generator for the specific file
-            // Path to the underlying documentation generation engine [ds]
             const cliPath = path.join(__dirname, 'cli.js');
             execSync(`node "${cliPath}" "${file}" --force${modeFlag}`, { stdio: 'inherit' });
             commentedAny = true;
@@ -91,8 +84,7 @@ try {
         }
     }
 
-    // Stage changes back to the repo if new documentation was generated [ds]
-    // If changes were made by the generator, stage and commit the result back to the repository
+    /** If any files were commented, stage and commit the changes [ds] */
     if (commentedAny) {
         const status = execSync('git diff --name-only', { encoding: 'utf8' }).trim();
         if (status.length > 0) {

package/bin/setup-hook.js

@@ -3,29 +3,26 @@ const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
 
-/**
- * Orchestrates the installation of Git pre-commit and post-commit hooks.
- * Sets up necessary directories and writes hook files with user-selected configuration.
-*/
+/** Installs Git hooks for the repository. [ds] */
 async function installHooks() {
     try {
-        // Determine the actual git directory path using git command line tool
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
         const hooksDir = path.join(gitDir, 'hooks');
-        // Ensure the hooks directory exists before attempting to write files
         if (!fs.existsSync(hooksDir)) {
             fs.mkdirSync(hooksDir, { recursive: true });
         }
 
         let modeChoice = '1';
-        // Prompt the user for mode selection only if running in an interactive terminal session
+        // Check if process is running in a TTY to prompt for user input [ds]
         if (process.stdout.isTTY) {
             const rl = readline.createInterface({
                 input: process.stdin,
                 output: process.stdout
             });
+            // Create a readline interface for user input [ds]
             const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
+            // Display a menu for the user to select the default commenting mode [ds]
             console.log('\nSelect default commenting mode for Git commits:');
             console.log('1. Balanced (mix of JSDoc and sparse inline comments)');
             console.log('2. Light (JSDoc block comments above functions only)');
@@ -35,7 +32,7 @@ async function installHooks() {
             rl.close();
         }
 
-        // Map user input to CLI arguments for the post-commit script execution
+        // Determine the command line arguments based on the chosen mode [ds]
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -43,7 +40,7 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Generate and write the pre-commit shell script to trigger tests before committing
+        // Define the path to the pre-commit hook file [ds]
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
@@ -53,15 +50,15 @@ if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
 fi
 `;
         fs.writeFileSync(preCommitHookPath, preCommitContent);
+        // Attempt to set the execute permissions for the pre-commit hook file [ds]
         try {
-            // Apply execute permissions to the hook file
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Normalize the path for cross-platform compatibility when injecting into shell script
+        // Define the path to the post-commit script [ds]
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Generate and write the post-commit shell script to execute the documentation generation
+        // Define the path to the post-commit hook file [ds]
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
@@ -69,19 +66,22 @@ echo "Auto-generating comments for files in the last commit..."
 node "${postCommitScript}"${modeArgs} || exit 1
 `;
         fs.writeFileSync(postCommitHookPath, postCommitContent);
-        // Apply execute permissions to the hook file
+        // Attempt to set the execute permissions for the post-commit hook file [ds]
         try {
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
+        // Display a success message if the hooks are installed successfully [ds]
         console.log('Success: Native Git pre-commit and post-commit hooks installed successfully!');
+    // Catch and handle any exceptions that occur during the installation process [ds]
     } catch (e) {
         console.warn('Warning: Could not set up Git hooks (not inside a git repository or git command missing).');
     }
 }
 
-// Execute installation automatically if this script is run as the entry point
+// Check if this script is being run directly (not being required as a module) [ds]
 if (require.main === module) {
     installHooks();
 }
+// Export the installHooks function as a module [ds]
 module.exports = installHooks;

package/lib/config.js

@@ -4,14 +4,8 @@ const os = require('os');
 const readline = require('readline');
 const configPath = path.join(os.homedir(), '.devsplainrc');
 
-/**
- * Retrieves configuration from environment variables or a local config file.
- * Runs a setup wizard if configuration is missing or forced.
- * @param {boolean} forceWizard - Whether to force the interactive setup.
- * @returns {Promise<Object>} The configuration object.
-*/
+/** Retrieves the configuration for the AI provider. If a configuration file exists and no forceWizard flag is provided, the existing configuration will be returned. Otherwise, the function will prompt the user to input their configuration details. [ds] */
 async function getConfig(forceWizard = false) {
-  // Priority 1: Check environment variables for configuration
   if (process.env.DEVSPLAIN_API_KEY || process.env.DEVSPLAIN_PROVIDER) {
     const provider = process.env.DEVSPLAIN_PROVIDER || 'gemini';
     const model = process.env.DEVSPLAIN_MODEL || (provider === 'gemini' ? 'gemini-2.0-flash' : 'llama-3.3-70b-versatile');
@@ -24,33 +18,34 @@ async function getConfig(forceWizard = false) {
     };
   }
 
-  // Priority 2: Check for existing config file or run setup wizard
+  // Check if configuration file exists or if forceWizard flag is set [ds]
   if (!fs.existsSync(configPath) || forceWizard) {
     const rl = readline.createInterface({
       input: process.stdin,
       output: process.stdout
     });
-    // Promisify readline to allow async flow
     const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
     let config = null;
     let confirmed = false;
 
-    // Loop until user confirms configuration choices
+    // Continuously prompt user for configuration details until confirmation [ds]
     while (!confirmed) {
       let baseUrl = "";
       let model = "";
       let provider = "";
 
+      // Display available AI provider options [ds]
       console.log("\nWhich AI Provider Do You want to use?");
       console.log("1. Groq (Free, Fast, Llama-3)");
       console.log("2. Gemini (Free Tier)");
       console.log("3. OpenAI (Paid)");
       console.log("4. Custom (Ollama, local, etc)");
 
+      // Get user's selected AI provider option [ds]
       const choice = await askQuestion("Select (1-4): ");
 
-      // Handle specific provider setup logic
+      // Handle selected AI provider option [ds]
       if (choice === '1') {
         provider = 'groq';
         baseUrl = 'https://api.groq.com/openai';
@@ -78,16 +73,18 @@ async function getConfig(forceWizard = false) {
         continue;
       }
 
+      // Get API key from user [ds]
       const apiKey = await askQuestion("Paste your API key (leave blank for local models): ");
 
+      // Display configuration summary [ds]
       console.log("\n--- Configuration Summary ---");
       console.log(`Provider: ${provider}`);
       console.log(`Model:    ${model}`);
       console.log(`Base URL: ${baseUrl || 'N/A'}`);
-      // Mask API key for security in display
       console.log(`API Key:  ${apiKey ? apiKey.substring(0, 4) + '*'.repeat(Math.max(0, apiKey.length - 4)) : 'None'}`);
       console.log("-----------------------------\n");
 
+      // Confirm configuration with user [ds]
       const confirm = await askQuestion("Does this look correct? (y/n, default: y): ");
       if (confirm.toLowerCase() === 'y' || confirm.trim() === '') {
         config = {
@@ -104,10 +101,10 @@ async function getConfig(forceWizard = false) {
 
     rl.close();
 
-    // Save finalized config to home directory
+    // Write configuration to file [ds]
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
     try {
-      // Ensure config file is not readable by other users (POSIX only)
+      // Set file permissions to prevent unauthorized access [ds]
       if (process.platform !== 'win32') {
         fs.chmodSync(configPath, 0o600);
       }
@@ -116,10 +113,11 @@ async function getConfig(forceWizard = false) {
 
     return config;
   } else {
-    // Priority 3: Load from existing file
+    // Read existing configuration from file [ds]
     const rawData = fs.readFileSync(configPath, 'utf8');
     return JSON.parse(rawData);
   }
 }
 
+// Export the getConfig function [ds]
 module.exports = { getConfig };

package/lib/llm.js

@@ -1,14 +1,7 @@
-/**
- * Fetches a URL with retry logic, timeout handling, and exponential backoff.
- * @param {string} url - The URL to fetch.
- * @param {object} options - Fetch options.
- * @param {number} maxRetries - Maximum number of retries.
- * @param {number} initialDelay - Initial delay in ms for backoff.
-*/
+/** Fetches a URL with retry functionality [ds] */
 async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000) {
     let lastError;
     for (let attempt = 0; attempt < maxRetries; attempt++) {
-        // AbortController to handle request timeouts
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 15000);
         try {
@@ -17,11 +10,9 @@ async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000)
                 signal: controller.signal
             });
             clearTimeout(timeoutId);
-            // If response is valid, return immediately
             if (response.ok) {
                 return response;
             }
-            // Retry on rate limit (429) or server-side errors (500-599)
             if (response.status === 429 || (response.status >= 500 && response.status < 600)) {
                 lastError = new Error(`HTTP Error ${response.status}: ${response.statusText}`);
             } else {
@@ -29,7 +20,6 @@ async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000)
             }
         } catch (err) {
             clearTimeout(timeoutId);
-            // Handle specific timeout case separately
             if (err.name === 'AbortError') {
                 lastError = new Error("Request timed out after 15 seconds");
             } else {
@@ -38,7 +28,6 @@ async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000)
         }
 
         if (attempt < maxRetries - 1) {
-            // Calculate exponential backoff delay
             const backoffDelay = initialDelay * Math.pow(2, attempt);
             console.warn(`[devsplain] AI request failed. Retrying in ${backoffDelay}ms... (Attempt ${attempt + 1}/${maxRetries})`);
             await new Promise(resolve => setTimeout(resolve, backoffDelay));
@@ -47,15 +36,8 @@ async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000)
     throw lastError;
 }
 
-/**
- * Generates documentation for code by sending it to an LLM provider.
- * @param {string} code - The source code to document.
- * @param {string} language - The programming language.
- * @param {object} config - Provider configuration (apiKey, model, etc.).
- * @param {string} mode - Operation mode (default, clean, light, full).
-*/
+/** Gets comments for the given code [ds] */
 async function getComments(code, language, config, mode = 'default') {
-    // Split into lines and prepend line numbers for LLM context
     const lines = code.split(/\r?\n/);
     const numberedCode = lines.map((line, index) => `${index + 1}: ${line}`).join('\n');
 
@@ -110,9 +92,10 @@ ${numberedCode}
         `.trim();
     }
 
+    // Initialize text response [ds]
     let textResponse = "";
 
-    // Branching logic for different LLM providers
+    // Check if provider is Gemini [ds]
     if (config.provider === 'gemini') {
         const url = `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent?key=${config.apiKey}`;
         let data;
@@ -135,6 +118,7 @@ ${numberedCode}
         }
         textResponse = data.candidates[0].content.parts[0].text;
     } 
+    // Otherwise, use a different provider [ds]
     else {
         const url = `${config.baseUrl}/v1/chat/completions`;
         let data;
@@ -164,7 +148,7 @@ ${numberedCode}
         textResponse = data.choices[0].message.content;
     }
 
-    // Extract JSON array from LLM response text
+    // Clean up the text response [ds]
     let cleanText = textResponse.trim();
     const start = cleanText.indexOf('[');
     const end = cleanText.lastIndexOf(']');
@@ -172,8 +156,8 @@ ${numberedCode}
         cleanText = cleanText.substring(start, end + 1);
     }
 
+    // Parse the response as JSON [ds]
     let parsed;
-    // Validate response format and schema integrity
     try {
         parsed = JSON.parse(cleanText);
     } catch (e) {
@@ -184,6 +168,7 @@ ${numberedCode}
         throw new Error("Schema Error: LLM response is not a JSON array.");
     }
 
+    // Validate the parsed response [ds]
     for (const item of parsed) {
         if (typeof item !== 'object' || item === null) {
             throw new Error("Schema Error: Array elements must be objects.");
@@ -202,7 +187,6 @@ ${numberedCode}
             }
 
             const trimmedComment = item.comment.trim();
-            // Sanity check for valid comment syntax
             const startsWithCommentMarker = 
                 trimmedComment.startsWith('//') || 
                 trimmedComment.startsWith('/*') || 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devsplain",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "An agent-agnostic CLI tool that automatically adds JSDoc and inline comments to your code using free LLMs.",
   "author": "mwahaj36",
   "license": "MIT",