devsplain 1.5.6 → 1.7.0

package/README.md

@@ -6,9 +6,10 @@ 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.
-- **Local Deterministic Scrubber**: The `--clean` flag strips comments locally using a deterministic lexical state machine—no LLM calls, API keys, or internet required.
+- **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.
 - **Git Hook Automation**: Supports an automated two-commit Git hook workflow (`pre-commit` for quality, `post-commit` for auto-generated documentation commits) that prevents recursive commit loops.
 - **Bring Your Own LLM**: Native setup wizard for Groq, Gemini, OpenAI, or any OpenAI-compatible API endpoint (like Ollama or LMStudio).
 - **Exponential Backoff**: Resilient AI request handler that automatically retries rate-limited requests with exponential backoff.
@@ -34,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
@@ -78,7 +92,8 @@ devsplain <file-or-directory> [options]
 | `--full` | Aggressive commenting. Explains complex logic blocks line-by-line inside functions. |
 | `--dry-run` | Preview comments in the terminal without writing to files. Prompts for manual save confirmation. |
 | `--force` | Bypasses the safety block check that prevents running `devsplain` on a dirty Git working tree. |
-| `--clean` | Scrubber mode. Deterministically removes all comments and docstrings from source files. |
+| `--clean` | Scrubber mode. Deterministically removes only devsplain-generated comments tagged with `[ds]`, preserving your manual comments. |
+| `--prune` | Destructive scrubber mode. Removes ALL comments and docstrings from source files, including your own manual comments. |
 | `--provider <name>`| Temporary one-off override for the AI provider (`gemini`, `groq`, `openai`, `custom`) for this command run only (does not modify the saved config file). |
 | `--model <name>` | Temporary one-off override for the model name for this command run only. |
 | `--api-key <key>` | Temporary one-off override for the API key for this command run only. |
@@ -97,9 +112,12 @@ devsplain src/index.js --light
 # Deep logic commenting on a folder (skips node_modules, .git, etc.)
 devsplain src/ --full
 
-# Clean and scrub comments from your codebase locally without AI calls
+# Clean and scrub AI-generated comments locally without API calls
 devsplain lib/ --clean
 
+# Destructively remove ALL comments (both AI and manual) from a folder
+devsplain lib/ --prune
+
 # Headless run using overriding credentials
 devsplain src/utils.ts --provider gemini --model gemini-2.0-flash --api-key YOUR_KEY
 ```

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,7 +23,7 @@ function isGitDirty() {
     return false;
 }
 
-/** 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;
@@ -97,7 +97,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
 }
 
-/** 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());
@@ -133,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;
@@ -146,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;
@@ -182,6 +199,7 @@ function analyzeComments(lines, ext = '') {
                         continue;
                     }
                 }
+            // Check for string literals in non-Python files [ds]
             } else {
                 if (!inSingle && !inDouble) {
                     if (line[j] === '`') {
@@ -221,6 +239,7 @@ function analyzeComments(lines, ext = '') {
                     }
                 }
             }
+            // Increment character index [ds]
             j++;
         }
         if (!isPython) {
@@ -248,7 +267,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** 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';
@@ -258,22 +277,68 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
 
     const annotated = originalLines.map((text, index) => ({ text, originalIndex: index }));
     let analysis = null;
+    let dsBlocks = new Set();
 
-    if (mode === 'clean') {
+    if (mode === 'clean' || mode === 'prune') {
         analysis = analyzeComments(originalLines, ext);
         const finalDeletions = new Set();
+        if (mode === 'clean') {
+            let i = 0;
+            while (i < originalLines.length) {
+                if (analysis[i].isInsideBlock) {
+                    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);
+                        }
+                    }
+                    i = end;
+                } else {
+                    i++;
+                }
+            }
+        }
+
         for (let i = 0; i < originalLines.length; i++) {
             const lineNum = i + 1;
-            if (originalLines[i].trim().startsWith('#!')) {
+            const lineStr = originalLines[i];
+            const lineAnalysis = analysis[i];
+
+            if (lineStr.trim().startsWith('#!')) {
                 continue;
             }
-            if (analysis[i].isPureComment) {
-                finalDeletions.add(lineNum);
-            } else if (analysis[i].commentStartIndex !== -1) {
-                annotated[i].text = originalLines[i].slice(0, analysis[i].commentStartIndex).trimEnd();
+
+            if (mode === 'prune') {
+                if (lineAnalysis.isPureComment) {
+                    finalDeletions.add(lineNum);
+                } else if (lineAnalysis.commentStartIndex !== -1) {
+                    annotated[i].text = lineStr.slice(0, lineAnalysis.commentStartIndex).trimEnd();
+                }
+            } else if (mode === 'clean') {
+                const isDsBlockLine = dsBlocks.has(lineNum);
+                const hasDsInline = lineStr.includes('[ds]');
+
+                if (lineAnalysis.isPureComment) {
+                    if (isDsBlockLine || hasDsInline) {
+                        finalDeletions.add(lineNum);
+                    }
+                } else if (lineAnalysis.commentStartIndex !== -1) {
+                    if (isDsBlockLine || hasDsInline) {
+                        annotated[i].text = lineStr.slice(0, lineAnalysis.commentStartIndex).trimEnd();
+                    }
+                }
             }
         }
 
+
         for (const c of validComments) {
             const lineIdx = c.line - 1;
             if (lineIdx >= 0 && lineIdx < originalLines.length) {
@@ -324,9 +389,23 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             const indentMatch = targetLine.match(/^([ \t]*)/);
             const indentation = indentMatch ? indentMatch[1] : '';
 
-            const commentLines = c.comment.split(/\r?\n/).map(line => {
-                const trimmed = line.trimStart();
+            const commentLines = c.comment.split(/\r?\n/).map((line, idx) => {
+                let trimmed = line.trimStart();
                 if (!trimmed) return '';
+
+                const isSingleLine = trimmed.startsWith('//') || trimmed.startsWith('#') || trimmed.startsWith('--');
+                const isBlockEnd = trimmed.endsWith('*/') || trimmed.endsWith('-->');
+
+                if (isSingleLine) {
+                    trimmed = trimmed + ' [ds]';
+                } else if (idx === 0) {
+                    if (isBlockEnd) {
+                        trimmed = trimmed.replace(/(\*\/|-->)$/, '[ds] $1');
+                    } else {
+                        trimmed = trimmed + ' [ds]';
+                    }
+                }
+
                 if (trimmed.startsWith('*') && !trimmed.startsWith('*/') && !trimmed.startsWith('/*')) {
                     return indentation + ' ' + trimmed;
                 }
@@ -348,12 +427,16 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
         if (text === originalLine) {
             return true;
         }
-        if (mode === 'clean' && analysis) {
+        if ((mode === 'clean' || mode === 'prune') && analysis) {
             const lineAnalysis = analysis[origIdx];
             if (lineAnalysis && lineAnalysis.commentStartIndex !== -1 && !lineAnalysis.isPureComment) {
-                const expectedStripped = originalLine.slice(0, lineAnalysis.commentStartIndex).trimEnd();
-                if (text === expectedStripped) {
-                    return true;
+                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) {
+                        return true;
+                    }
                 }
             }
         }
@@ -376,7 +459,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** 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));
@@ -395,6 +478,8 @@ Options:
   --full              Add detailed JSDoc/block comments and inline comments
   --dry-run           Preview comments without writing to file
   --force             Bypass the dirty Git tree safety check
+  --clean             Scrub only devsplain-generated [ds] comments
+  --prune             Destructively scrub ALL comments from files
   --provider <name>   Override AI provider (gemini, groq, openai, custom)
   --model <name>      Override AI model name
   --api-key <key>     Override API key for the provider
@@ -461,6 +546,7 @@ Options:
     if (args.includes('--light')) mode = 'light';
     if (args.includes('--full')) mode = 'full';
     if (args.includes('--clean')) mode = 'clean';
+    if (args.includes('--prune')) mode = 'prune';
     const isDryRun = args.includes('--dry-run');
     const isForce = args.includes('--force');
 
@@ -493,8 +579,8 @@ Options:
     let successCount = 0;
     let failCount = 0;
 
-    /** 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()) {
@@ -503,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)) {
@@ -540,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} ---`);
@@ -590,7 +677,7 @@ Options:
     rl.close();
 }
 
-// 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,40 +3,43 @@ const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
 
-/** 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
+    // 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 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/);
 
+    /** 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 command-line arguments for commenting mode [ds]
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
@@ -44,14 +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 fetch the file content from the previous commit state for comparison
                 contentPrev = execSync(`git show HEAD~1:"${file}"`, { 
                     encoding: 'utf8', 
                     stdio: ['ignore', 'pipe', 'ignore'] 
@@ -59,11 +61,10 @@ try {
             } catch (prevErr) {
             }
 
+            // Check if the file has been modified beyond just comments [ds]
             if (contentPrev) {
-                // Strip comments from head and previous versions to detect if logic actually changed
-                const cleanHead = spliceComments(contentHead, [], 'clean', ext);
-                const cleanPrev = spliceComments(contentPrev, [], 'clean', ext);
-                // Skip processing if only comments were modified in the commit
+                const cleanHead = spliceComments(contentHead, [], 'prune', ext);
+                const cleanPrev = spliceComments(contentPrev, [], 'prune', ext);
                 if (cleanHead === cleanPrev) {
                     console.log(`[devsplain] Skipping ${file}: commit contains only comment changes.`);
                     continue;
@@ -72,9 +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
             const cliPath = path.join(__dirname, 'cli.js');
             execSync(`node "${cliPath}" "${file}" --force${modeFlag}`, { stdio: 'inherit' });
             commentedAny = true;
@@ -83,7 +84,7 @@ try {
         }
     }
 
-    // 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,13 +3,9 @@ const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
 
-/**
- * Orchestrates the installation of Git pre-commit and post-commit hooks.
- * Detects the local .git directory and configures hooks with user-specified mode.
-*/
+/** Installs Git hooks for the repository. [ds] */
 async function installHooks() {
     try {
-        // Determine the path to the .git directory
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
         const hooksDir = path.join(gitDir, 'hooks');
         if (!fs.existsSync(hooksDir)) {
@@ -17,15 +13,16 @@ async function installHooks() {
         }
 
         let modeChoice = '1';
-        // Interact with user via terminal to select documentation verbosity
+        // 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
             });
-            // Promisify readline to allow async flow control
+            // 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 selected mode to command-line arguments for the post-commit script
+        // Determine the command line arguments based on the chosen mode [ds]
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -43,23 +40,25 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Create the executable pre-commit script
+        // 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
-echo "Running pre-commit tests..."
-npm test || exit 1
+if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
+  echo "Running pre-commit tests..."
+  npm test || exit 1
+fi
 `;
         fs.writeFileSync(preCommitHookPath, preCommitContent);
+        // Attempt to set the execute permissions for the pre-commit hook file [ds]
         try {
-            // Ensure the hook file is executable
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Locate the source script for post-commit actions
+        // Define the path to the post-commit script [ds]
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Create the executable post-commit script that calls the documentation engine
+        // 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
@@ -67,18 +66,22 @@ echo "Auto-generating comments for files in the last commit..."
 node "${postCommitScript}"${modeArgs} || exit 1
 `;
         fs.writeFileSync(postCommitHookPath, postCommitContent);
+        // Attempt to set the execute permissions for the post-commit hook file [ds]
         try {
-            // Ensure the hook file is executable
             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).');
     }
 }
 
+// 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.5.6",
+  "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",