devsplain 2.0.0 → 2.1.0

package/README.md

@@ -1,12 +1,10 @@
 # devsplain
-An agent-agnostic CLI tool that adds JSDoc and inline comments using state-of-the-art LLMs while preserving non-comment source lines byte-for-byte through deterministic verification.
 
-![devsplain demo](sample.gif)
+**devsplain never rewrites executable code**—it's a single-shot CLI that adds JSDoc and inline comments across 22 languages using LLMs, preserving non-comment source lines byte-for-byte through deterministic verification.
 
-devsplain never rewrites executable code.
-If the original source cannot be reproduced exactly after comment insertion, the operation aborts.
+![devsplain demo](sample.gif)
 
-Unlike interactive AI editors, `devsplain` is a single-shot CLI designed for batch documentation passes, CI pipelines, and git hook automation—no agent overhead, no per-file confirmation loops.
+Unlike interactive AI editors, `devsplain` is designed for batch documentation passes, CI pipelines, and git hook automation—no agent overhead, no per-file confirmation loops.
 
 > [!TIP]
 > **Built with devsplain**
@@ -16,7 +14,7 @@ Unlike interactive AI editors, `devsplain` is a single-shot CLI designed for bat
 ## Key Features
 
 - **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.
+- **Multi-Language support**: Works across 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.
 - **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.
@@ -46,14 +44,14 @@ The engine tracks lexical state across template strings, single quotes, double q
 
 ### The `[ds]` AI Tag Guarantee
 Every single comment generated by the LLM is forcibly prefixed with a `[ds]` tag (e.g., `// [ds] This function handles...`). 
-This guarantees that the local `devsplain` lexer can mathematically differentiate between your human-written manual comments and the AI-generated comments. 
+This guarantees that the local `devsplain` lexer can lexically distinguish between your human-written manual comments and the AI-generated comments. 
 When you run the `--clean` command, the lexer looks specifically for the `[ds]` prefix and surgically removes only the AI-generated comments, safely preserving 100% of your manual documentation.
 
 ### Why Not AST Verification?
 
-AST verification would require language-specific parser dependencies for every supported language.
+AST parsers are language-specific. Supporting 22 languages would require 22 native parser dependencies, which defeats the zero-dependency architecture entirely.
 
-`devsplain` instead uses deterministic source-preservation verification:
+The line-splicing + round-trip diff approach achieves equivalent guarantees without any of that bloat. This is not a compromise—it's the right answer for this tool's constraints:
 
 1. Original source is loaded.
 2. Comments are inserted.
@@ -178,7 +176,9 @@ SKIP_DEVSPLAIN=1 git commit -m "my commit message"
 ```
 
 ### Forcing or Skipping Auto-Prune
-If you have configured `autoPrune` (aggressive overwrite) in your `~/.devsplainrc` but want to change the behavior for a specific commit:
+(If `autoPrune: true` is set in your `~/.devsplainrc` via the `--config` wizard, the hook scrubs all existing comments before regenerating them.)
+
+If you want to change this behavior for a specific commit:
 - To **force an overwrite** (destroying all human/AI comments before generating new ones) regardless of your config:
   ```bash
   DS_OVER=1 git commit -m "overwrite docs"

package/bin/cli.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 let rl;
 let askQuestion;
 
-/** Checks if the Git working tree is dirty [ds] */
+/** Checks if the 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,46 +23,178 @@ function isGitDirty() {
     return false;
 }
 
-/** Checks if a line is inside a string literal [ds] */
+/** Checks if a line of code is inside a string literal [ds] */
 function isLineInsideString(lines, targetLineIndex, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
+    const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
+    const isRustOrSwift = ['.rs', '.swift'].includes(ext.toLowerCase());
+    const isCpp = ['.cpp', '.cc', '.cxx', '.c', '.h', '.hpp'].includes(ext.toLowerCase());
+    const isJS = ['.js', '.jsx', '.ts', '.tsx'].includes(ext.toLowerCase());
     let inBacktick = false;
     let inTripleDouble = false;
     let inTripleSingle = false;
     let inSingle = false;
     let inDouble = false;
-
+    let inBlockJS = false;
+    let inBlockHTML = false;
+    let blockDepthJS = 0;
+    let inCppRawString = false;
+    let cppRawDelimiter = '';
+    let inRegex = false;
     for (let i = 0; i < targetLineIndex; i++) {
         const line = lines[i];
         let j = 0;
         while (j < line.length) {
+            if (inBlockJS) {
+                if (line.slice(j, j + 2) === '/*') {
+                    if (isRustOrSwift) blockDepthJS++;
+                    j += 2;
+                    continue;
+                }
+                if (line.slice(j, j + 2) === '*/') {
+                    if (isRustOrSwift && blockDepthJS > 1) {
+                        blockDepthJS--;
+                    } else {
+                        inBlockJS = false;
+                        blockDepthJS = 0;
+                    }
+                    j += 2;
+                    continue;
+                }
+                j++;
+                continue;
+            }
+            if (inCppRawString) {
+                if (line.slice(j, j + 2 + cppRawDelimiter.length) === ')' + cppRawDelimiter + '"') {
+                    inCppRawString = false;
+                    j += 2 + cppRawDelimiter.length;
+                    continue;
+                }
+                j++;
+                continue;
+            }
+            if (inRegex) {
+                let escaped = false;
+                let k = j - 1;
+                while (k >= 0 && line[k] === '\\') {
+                    escaped = !escaped;
+                    k--;
+                }
+                if (line[j] === '/' && !escaped) {
+                    inRegex = false;
+                }
+                j++;
+                continue;
+            }
+            if (inBlockHTML) {
+                if (line.slice(j, j + 3) === '-->') {
+                    inBlockHTML = false;
+                    j += 3;
+                    continue;
+                }
+                j++;
+                continue;
+            }
+            // Check if comment starts (skip processing quotes if we are entering a comment)
+            if (!inSingle && !inDouble && !inBacktick && !inTripleSingle && !inTripleDouble) {
+                if (isPython) {
+                    if (line[j] === '#') {
+                        break; // Ignore rest of line
+                    }
+                } else if (isHTML) {
+                    if (line.slice(j, j + 4) === '<!--') {
+                        inBlockHTML = true;
+                        j += 4;
+                        continue;
+                    }
+                    if (line.slice(j, j + 2) === '/*') {
+                        inBlockJS = true;
+                        j += 2;
+                        continue;
+                    }
+                    if (line.slice(j, j + 2) === '//') {
+                        break; // Ignore rest of line
+                    }
+                } else {
+                    if (line.slice(j, j + 2) === '//') {
+                        break; // Ignore rest of line
+                    }
+                    if (line.slice(j, j + 2) === '/*') {
+                        inBlockJS = true;
+                        blockDepthJS = 1;
+                        j += 2;
+                        continue;
+                    }
+                    const isShellOrRuby = ['.sh', '.rb', '.php'].includes(ext.toLowerCase());
+                    if (isShellOrRuby && line[j] === '#') {
+                        break; // Ignore rest of line
+                    }
+                    if (isCpp && line[j] === 'R' && line[j+1] === '"') {
+                        const match = line.slice(j).match(/^R"([^()\\\s]{0,16})\(/);
+                        if (match) {
+                            cppRawDelimiter = match[1];
+                            inCppRawString = true;
+                            j += match[0].length;
+                            continue;
+                        }
+                    }
+                    if (isJS && line[j] === '/') {
+                        let k = j - 1;
+                        while (k >= 0 && /\s/.test(line[k])) k--;
+                        let isRegex = false;
+                        if (k < 0) {
+                            isRegex = true;
+                        } else {
+                            const prevChar = line[k];
+                            if (/[=({\[:,;!+*&|?<>-]/.test(prevChar)) {
+                                isRegex = true;
+                            } else {
+                                const prefix = line.slice(0, k + 1);
+                                if (/(?:return|typeof|yield|await|throw)\s*$/.test(prefix)) {
+                                    isRegex = true;
+                                }
+                            }
+                        }
+                        if (isRegex) {
+                            inRegex = true;
+                            j++;
+                            continue;
+                        }
+                    }
+                }
+            }
             if (isPython) {
-                if (!inTripleSingle) {
+                if (!inTripleSingle && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === '"""') {
                         inTripleDouble = !inTripleDouble;
                         j += 3;
                         continue;
                     }
                 }
-                if (!inTripleDouble) {
+                if (!inTripleDouble && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === "'''") {
                         inTripleSingle = !inTripleSingle;
                         j += 3;
                         continue;
                     }
                 }
-            } else {
-                if (!inSingle && !inDouble && line[j] === '`') {
-                    let escaped = false;
-                    let k = j - 1;
-                    while (k >= 0 && line[k] === '\\') {
-                        escaped = !escaped;
-                        k--;
-                    }
-                    if (!escaped) {
-                        inBacktick = !inBacktick;
+            }
+            if (!inTripleSingle && !inTripleDouble) {
+                if (!isPython) {
+                    if (!inSingle && !inDouble) {
+                        if (line[j] === '`') {
+                        let escaped = false;
+                        let k = j - 1;
+                        while (k >= 0 && line[k] === '\\') {
+                            escaped = !escaped;
+                            k--;
+                        }
+                        if (!escaped) {
+                            inBacktick = !inBacktick;
+                        }
                     }
                 }
+                }
                 if (!inBacktick) {
                     if (line[j] === '"' && !inSingle) {
                         let escaped = false;
@@ -89,18 +221,22 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
             }
             j++;
         }
-        if (!isPython) {
+        const resetsAtLineEnd = ['.js', '.jsx', '.ts', '.tsx', '.java', '.c', '.cpp', '.cs', '.go', '.swift', '.kt', '.dart'].includes(ext.toLowerCase());
+        if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
         }
     }
-    return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
+    return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble || inCppRawString || inRegex;
 }
 
-/** Analyzes comments in a list of lines [ds] */
+/** Analyzes the comments in a given set of code lines [ds] */
 function analyzeComments(lines, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
+    const isRustOrSwift = ['.rs', '.swift'].includes(ext.toLowerCase());
+    const isCpp = ['.cpp', '.cc', '.cxx', '.c', '.h', '.hpp'].includes(ext.toLowerCase());
+    const isJS = ['.js', '.jsx', '.ts', '.tsx'].includes(ext.toLowerCase());
     const analysis = [];
     let inBacktick = false;
     let inTripleDouble = false;
@@ -109,6 +245,10 @@ function analyzeComments(lines, ext = '') {
     let inDouble = false;
     let inBlockJS = false;
     let inBlockHTML = false;
+    let blockDepthJS = 0;
+    let inCppRawString = false;
+    let cppRawDelimiter = '';
+    let inRegex = false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         let commentStartIndex = -1;
@@ -116,14 +256,46 @@ function analyzeComments(lines, ext = '') {
         let j = 0;
         while (j < line.length) {
             if (inBlockJS) {
+                if (line.slice(j, j + 2) === '/*') {
+                    if (isRustOrSwift) blockDepthJS++;
+                    j += 2;
+                    continue;
+                }
                 if (line.slice(j, j + 2) === '*/') {
-                    inBlockJS = false;
+                    if (isRustOrSwift && blockDepthJS > 1) {
+                        blockDepthJS--;
+                    } else {
+                        inBlockJS = false;
+                        blockDepthJS = 0;
+                    }
                     j += 2;
                     continue;
                 }
                 j++;
                 continue;
             }
+            if (inCppRawString) {
+                if (line.slice(j, j + 2 + cppRawDelimiter.length) === ')' + cppRawDelimiter + '"') {
+                    inCppRawString = false;
+                    j += 2 + cppRawDelimiter.length;
+                    continue;
+                }
+                j++;
+                continue;
+            }
+            if (inRegex) {
+                let escaped = false;
+                let k = j - 1;
+                while (k >= 0 && line[k] === '\\') {
+                    escaped = !escaped;
+                    k--;
+                }
+                if (line[j] === '/' && !escaped) {
+                    inRegex = false;
+                }
+                j++;
+                continue;
+            }
             if (inBlockHTML) {
                 if (line.slice(j, j + 3) === '-->') {
                     inBlockHTML = false;
@@ -139,16 +311,6 @@ function analyzeComments(lines, ext = '') {
                         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;
@@ -174,33 +336,69 @@ function analyzeComments(lines, ext = '') {
                     if (line.slice(j, j + 2) === '/*') {
                         commentStartIndex = j;
                         inBlockJS = true;
+                        blockDepthJS = 1;
                         j += 2;
                         continue;
                     }
-                    if (line[j] === '#') {
+                    const isShellOrRuby = ['.sh', '.rb', '.php'].includes(ext.toLowerCase());
+                    if (isShellOrRuby && line[j] === '#') {
                         commentStartIndex = j;
                         break;
                     }
+                    if (isCpp && line[j] === 'R' && line[j+1] === '"') {
+                        const match = line.slice(j).match(/^R"([^()\\\s]{0,16})\(/);
+                        if (match) {
+                            cppRawDelimiter = match[1];
+                            inCppRawString = true;
+                            j += match[0].length;
+                            continue;
+                        }
+                    }
+                    if (isJS && line[j] === '/') {
+                        let k = j - 1;
+                        while (k >= 0 && /\s/.test(line[k])) k--;
+                        let isRegex = false;
+                        if (k < 0) {
+                            isRegex = true;
+                        } else {
+                            const prevChar = line[k];
+                            if (/[=({\[:,;!+*&|?<>-]/.test(prevChar)) {
+                                isRegex = true;
+                            } else {
+                                const prefix = line.slice(0, k + 1);
+                                if (/(?:return|typeof|yield|await|throw)\s*$/.test(prefix)) {
+                                    isRegex = true;
+                                }
+                            }
+                        }
+                        if (isRegex) {
+                            inRegex = true;
+                            j++;
+                            continue;
+                        }
+                    }
                 }
             }
             if (isPython) {
-                if (!inTripleSingle) {
+                if (!inTripleSingle && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === '"""') {
                         inTripleDouble = !inTripleDouble;
                         j += 3;
                         continue;
                     }
                 }
-                if (!inTripleDouble) {
+                if (!inTripleDouble && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === "'''") {
                         inTripleSingle = !inTripleSingle;
                         j += 3;
                         continue;
                     }
                 }
-            } else {
-                if (!inSingle && !inDouble) {
-                    if (line[j] === '`') {
+            }
+            if (!inTripleSingle && !inTripleDouble) {
+                if (!isPython) {
+                    if (!inSingle && !inDouble) {
+                        if (line[j] === '`') {
                         let escaped = false;
                         let k = j - 1;
                         while (k >= 0 && line[k] === '\\') {
@@ -212,6 +410,7 @@ function analyzeComments(lines, ext = '') {
                         }
                     }
                 }
+                }
                 if (!inBacktick) {
                     if (line[j] === '"' && !inSingle) {
                         let escaped = false;
@@ -239,7 +438,8 @@ function analyzeComments(lines, ext = '') {
             }
             j++;
         }
-        if (!isPython) {
+        const resetsAtLineEnd = ['.js', '.jsx', '.ts', '.tsx', '.java', '.c', '.cpp', '.cs', '.go', '.swift', '.kt', '.dart'].includes(ext.toLowerCase());
+        if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
         }
@@ -264,7 +464,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splices comments into a list of lines [ds] */
+/** Splices comments into the provided code data [ds] */
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -286,7 +486,7 @@ 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 blockStart = Math.max(0, start - 1);
                     let blockEnd = end - 1;
                     let hasDs = false;
                     for (let k = blockStart; k <= blockEnd; k++) {
@@ -600,8 +800,8 @@ Options:
     ];
     const allIgnored = [...defaultIgnoredFolders, ...userIgnorePatterns];
 
+    /** Checks if a path is ignored based on the ignore patterns [ds] */
     function isPathIgnored(targetPath) {
-        // Checks if a path is ignored [ds]
         const filename = path.basename(targetPath);
         for (const pattern of allIgnored) {
             const cleanPattern = pattern.replace(/\/$/, '').replace(/\\$/, '');
@@ -611,7 +811,7 @@ Options:
         return false;
     }
 
-    /** Processes a path, scanning directories or analyzing files [ds] */
+    /** Processes a given path, which can be a file or directory [ds] */
     async function processPath(targetPath) {
         const stats = fs.statSync(targetPath);
 

package/bin/setup-hook.js

@@ -3,7 +3,7 @@ const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
 
-/** Installs Git hooks for auto-generating comments [ds] */
+/** Installs Git hooks and configures commit settings [ds] */
 async function installHooks() {
     try {
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
@@ -13,9 +13,8 @@ async function installHooks() {
             fs.mkdirSync(hooksDir, { recursive: true });
         }
 
-        // Default commenting mode for Git commits [ds]
         let modeChoice = '1';
-        // Check if running in a TTY to prompt user for commenting mode [ds]
+        // Check if process is run in a TTY environment [ds]
         if (process.stdout.isTTY) {
             const rl = readline.createInterface({
                 input: process.stdin,
@@ -23,15 +22,25 @@ async function installHooks() {
             });
             const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
+            // Prompt 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)');
             console.log('3. Full (aggressive inline commenting)');
-            const answer = await askQuestion('Select (1-3, default: 1): ');
-            modeChoice = answer.trim() || '1';
+            
+            // Validate user input for commenting mode [ds]
+            while (true) {
+                const answer = (await askQuestion('Select (1-3, default: 1): ')).trim();
+                if (answer === '' || ['1', '2', '3'].includes(answer)) {
+                    modeChoice = answer || '1';
+                    break;
+                }
+                console.log('Invalid choice. Please select 1, 2, or 3.');
+            }
             rl.close();
         }
 
+        // Determine mode arguments based on user choice [ds]
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -39,7 +48,7 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Path to pre-commit hook script [ds]
+        // Define the pre-commit hook script [ds]
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
@@ -48,16 +57,16 @@ if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
   npm test || exit 1
 fi
 `;
-        // Write pre-commit hook content to file [ds]
+        // Write the pre-commit hook to the Git hooks directory [ds]
         fs.writeFileSync(preCommitHookPath, preCommitContent);
         try {
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Path to post-commit script [ds]
+        // Define the post-commit script path [ds]
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Path to post-commit hook script [ds]
+        // Define the post-commit hook script [ds]
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
@@ -69,11 +78,11 @@ node "${postCommitScript}"${modeArgs} || exit 1
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
+        // Inform the user about the successful installation of the post-commit hook [ds]
         console.log(`[devsplain] Git post-commit hook successfully installed at: ${postCommitHookPath}`);
 
-        // Log successful installation of post-commit hook [ds]
+        // Check if a .devsplainignore file exists in the Git root directory [ds]
         const ignorePath = path.join(gitRoot, '.devsplainignore');
-        // Check if .devsplainignore file exists [ds]
         if (!fs.existsSync(ignorePath)) {
             const defaultIgnore = `node_modules/
 .git/
@@ -102,9 +111,9 @@ fixtures/
     }
 }
 
-// Run installHooks if this script is the main module [ds]
+// Check if the script is run as the main module [ds]
 if (require.main === module) {
     installHooks();
 }
-// Export installHooks function [ds]
+// Export the installHooks function for external use [ds]
 module.exports = installHooks;

package/lib/config.js

@@ -4,7 +4,7 @@ const os = require('os');
 const readline = require('readline');
 const configPath = path.join(os.homedir(), '.devsplainrc');
 
-/** Asks the user for a secret input, such as an API key, without echoing the input to the console. [ds] */
+/** Asks the user for a secret input (e.g., an API key) without echoing the input to the console. [ds] */
 function askSecret(query) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -14,7 +14,6 @@ function askSecret(query) {
     process.stdout.write(query);
     process.stdin.setRawMode(true);
     let key = '';
-    // Handle key presses, including enter, backspace, and Ctrl+C [ds]
     const onData = (char) => {
       char = char.toString();
       if (char === '\n' || char === '\r') {
@@ -34,7 +33,7 @@ function askSecret(query) {
   });
 }
 
-/** Retrieves the configuration, either from environment variables or by prompting the user to set up a configuration file. [ds] */
+/** Attempts to fetch the configuration settings, either from environment variables or by prompting the user. [ds] */
 async function getConfig(forceWizard = false) {
   if (process.env.DEVSPLAIN_API_KEY || process.env.DEVSPLAIN_PROVIDER) {
     const provider = process.env.DEVSPLAIN_PROVIDER || 'gemini';
@@ -47,8 +46,8 @@ async function getConfig(forceWizard = false) {
       baseUrl
     };
   }
+// If the configuration file doesn't exist, or if we're forcing the wizard, let's prompt the user for configuration. [ds]
 
-  // If no configuration file exists or the forceWizard flag is set, prompt the user to set up a configuration [ds]
   if (!fs.existsSync(configPath) || forceWizard) {
     let rl = readline.createInterface({
       input: process.stdin,
@@ -59,12 +58,13 @@ async function getConfig(forceWizard = false) {
     let config = null;
     let confirmed = false;
 
+    // Keep prompting the user until they confirm their configuration settings. [ds]
     while (!confirmed) {
       let baseUrl = "";
       let model = "";
       let provider = "";
 
-      // Display a menu of available AI providers [ds]
+      // Display the list of available AI providers to the user. [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)");
@@ -94,8 +94,16 @@ async function getConfig(forceWizard = false) {
         model = customModel.trim() || 'gpt-4o';
       } else if (choice === '4') {
         provider = 'custom';
-        model = await askQuestion("Model name (e.g., llama3): ");
-        baseUrl = await askQuestion("Base URL (e.g., http://localhost:11434): ");
+        while (true) {
+          model = (await askQuestion("Model name (e.g., llama3): ")).trim();
+          if (model) break;
+          console.log("Model name cannot be empty.");
+        }
+        while (true) {
+          baseUrl = (await askQuestion("Base URL (e.g., http://localhost:11434): ")).trim();
+          if (baseUrl) break;
+          console.log("Base URL cannot be empty.");
+        }
       } else if (choice === '5') {
         provider = 'claude';
         baseUrl = 'https://api.anthropic.com';
@@ -107,26 +115,48 @@ async function getConfig(forceWizard = false) {
         continue;
       }
 
+      // Get the API key from the user. [ds]
       let apiKey = '';
-      // If running in a TTY, use a secure method to prompt for the API key [ds]
-      if (process.stdin.isTTY) {
-        rl.close();
-        apiKey = await askSecret("Paste your API key (leave blank for local models): ");
-
-        rl = readline.createInterface({
-          input: process.stdin,
-          output: process.stdout
-        });
-        askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
-      } else {
-        apiKey = await askQuestion("Paste your API key (leave blank for local models): ");
+      while (true) {
+        const promptMsg = provider === 'custom' 
+          ? "Paste your API key (leave blank for local models): " 
+          : "Paste your API key: ";
+
+        if (process.stdin.isTTY) {
+          rl.close();
+          apiKey = await askSecret(promptMsg);
+
+          rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+          });
+          askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+        } else {
+          apiKey = await askQuestion(promptMsg);
+        }
+
+        apiKey = apiKey.trim();
+        if (provider === 'custom' || apiKey) {
+          break;
+        }
+        console.log(`API key is required for provider '${provider}'.`);
       }
 
-      // Ask the user if they want to prune existing comments [ds]
-      const pruneAns = await askQuestion("Do you want devsplain to aggressively prune (overwrite) existing human/AI comments? (y/n, default: n): ");
-      const autoPrune = pruneAns.toLowerCase() === 'y';
+      // Ask the user if they want to enable auto-pruning of existing human/AI comments. [ds]
+      let autoPrune = false;
+      while (true) {
+        const pruneAns = (await askQuestion("Do you want devsplain to aggressively prune (overwrite) existing human/AI comments? (y/n, default: n): ")).trim().toLowerCase();
+        if (pruneAns === '' || pruneAns === 'n' || pruneAns === 'no') {
+          autoPrune = false;
+          break;
+        } else if (pruneAns === 'y' || pruneAns === 'yes') {
+          autoPrune = true;
+          break;
+        }
+        console.log("Invalid choice. Please enter 'y' or 'n'.");
+      }
 
-      // Display a summary of the configuration [ds]
+      // Display a summary of the user's configuration settings. [ds]
       console.log("\n--- Configuration Summary ---");
       console.log(`Provider:     ${provider}`);
       console.log(`Model:        ${model}`);
@@ -135,28 +165,31 @@ async function getConfig(forceWizard = false) {
       console.log(`Auto-Prune:   ${autoPrune ? 'Yes' : 'No'}`);
       console.log("-----------------------------\n");
 
-      // Confirm the configuration with the user [ds]
-      const confirm = await askQuestion("Does this look correct? (y/n, default: y): ");
-      if (confirm.toLowerCase() === 'y' || confirm.trim() === '') {
-        config = {
-          provider,
-          apiKey,
-          model,
-          baseUrl,
-          autoPrune
-        };
-        confirmed = true;
-      } else {
-        console.log("Let's restart the configuration setup.");
+      // Confirm the configuration settings with the user. [ds]
+      while (true) {
+        const confirm = (await askQuestion("Does this look correct? (y/n, default: y): ")).trim().toLowerCase();
+        if (confirm === '' || confirm === 'y' || confirm === 'yes') {
+          config = {
+            provider,
+            apiKey,
+            model,
+            baseUrl,
+            autoPrune
+          };
+          confirmed = true;
+          break;
+        } else if (confirm === 'n' || confirm === 'no') {
+          break;
+        }
+        console.log("Invalid choice. Please enter 'y' or 'n'.");
       }
     }
 
     rl.close();
 
-    // Write the configuration to a file [ds]
+    // Write the configuration settings to the config file. [ds]
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
     try {
-      // Set permissions on the configuration file to prevent other users from reading it [ds]
       if (process.platform !== 'win32') {
         fs.chmodSync(configPath, 0o600);
       }
@@ -170,4 +203,5 @@ async function getConfig(forceWizard = false) {
   }
 }
 
-module.exports = { getConfig };
+// Export the getConfig function for use in other modules. [ds]
+module.exports = { getConfig };

package/lib/llm.js

@@ -41,37 +41,14 @@ async function getComments(code, language, config, mode = 'default') {
     const lines = code.split(/\r?\n/);
     const numberedCode = lines.map((line, index) => `${index + 1}: ${line}`).join('\n');
 
-    let prompt = "";
-    if (mode === 'clean') {
-        prompt = `
-You are a code documentation scrubber. Analyze the following ${language} code which has line numbers prepended to it.
-Your goal is to identify all lines containing comments (both block/JSDoc and inline comments) and return their line numbers to delete them.
-
-CRITICAL RULES:
-1. You MUST respond with ONLY a raw, valid JSON array of objects. NO markdown formatting, NO backticks, NO explanations, NO text before or after the JSON.
-2. Each object must have exactly two properties: "line" (the integer line number of the comment line to delete) and "action" (which must be the string "delete").
-3. Do NOT include the original code in your response.
-4. If no comments are found, return an empty array: [].
-5. For block or JSDoc comments (e.g., starting with /* and ending with */), you MUST identify and return the line numbers of ALL lines in that block, including the opening /*, all intermediate lines, and the closing */. Do NOT leave trailing comment delimiters behind.
-
-Example Output:
-[
-  { "line": 4, "action": "delete" },
-  { "line": 5, "action": "delete" }
-]
-
-Here is the source code:
-${numberedCode}
-        `.trim();
-    } else {
-        let instruction = "Provide JSDoc/docstrings block comments above functions and sparse inline comments for complex logic.";
-        if (mode === 'light') {
-            instruction = "Provide ONLY JSDoc/docstrings above functions. Keep it minimal.";
-        } else if (mode === 'full') {
-            instruction = "Provide highly detailed JSDoc/docstrings above functions, and exhaustive step-by-step inline comments (using standard comment syntax like // or #) explaining every conditional branch, loop, variable assignment, and logical block inside function bodies. Do not be sparse; explain the code's execution flow in detail.";
-        }
+    let instruction = "Provide JSDoc/docstrings block comments above functions and sparse inline comments for complex logic.";
+    if (mode === 'light') {
+        instruction = "Provide ONLY JSDoc/docstrings above functions. Keep it minimal.";
+    } else if (mode === 'full') {
+        instruction = "Provide highly detailed JSDoc/docstrings above functions, and exhaustive step-by-step inline comments (using standard comment syntax like // or #) explaining every conditional branch, loop, variable assignment, and logical block inside function bodies. Do not be sparse; explain the code's execution flow in detail.";
+    }
 
-        prompt = `
+    let prompt = `
 You are a code documentation engine. Analyze the following ${language} code which has line numbers prepended to it.
 ${instruction}
 
@@ -89,8 +66,7 @@ Example Output:
 
 Here is the source code:
 ${numberedCode}
-        `.trim();
-    }
+    `.trim();
 
     // Initialize text response [ds]
     let textResponse = "";

package/package.json

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