devsplain 2.0.1 → 2.1.0

package/bin/cli.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 let rl;
 let askQuestion;
 
-/** Checks if the Git repository 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,10 +23,13 @@ function isGitDirty() {
     return false;
 }
 
-/** Checks if a line of code is inside a string [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;
@@ -34,19 +37,55 @@ function isLineInsideString(lines, targetLineIndex, 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 < 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) === '*/') {
-                    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;
@@ -65,7 +104,6 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
                 } else if (isHTML) {
                     if (line.slice(j, j + 4) === '<!--') {
                         inBlockHTML = true;
-                        // Check if current character is a backtick [ds]
                         j += 4;
                         continue;
                     }
@@ -83,6 +121,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
                     }
                     if (line.slice(j, j + 2) === '/*') {
                         inBlockJS = true;
+                        blockDepthJS = 1;
                         j += 2;
                         continue;
                     }
@@ -90,6 +129,38 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
                     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) {
@@ -125,7 +196,6 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
                 }
                 }
                 if (!inBacktick) {
-                    // Check if current character is a double quote [ds]
                     if (line[j] === '"' && !inSingle) {
                         let escaped = false;
                         let k = j - 1;
@@ -157,13 +227,16 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
             inDouble = false;
         }
     }
-    return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
+    return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble || inCppRawString || inRegex;
 }
 
-/** Analyzes comments in a given 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;
@@ -172,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;
@@ -179,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;
@@ -227,6 +336,7 @@ function analyzeComments(lines, ext = '') {
                     if (line.slice(j, j + 2) === '/*') {
                         commentStartIndex = j;
                         inBlockJS = true;
+                        blockDepthJS = 1;
                         j += 2;
                         continue;
                     }
@@ -235,6 +345,38 @@ function analyzeComments(lines, ext = '') {
                         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) {
@@ -281,7 +423,6 @@ function analyzeComments(lines, ext = '') {
                             inDouble = !inDouble;
                         }
                     }
-                    // Check if current character is a single quote [ds]
                     else if (line[j] === "'" && !inDouble) {
                         let escaped = false;
                         let k = j - 1;
@@ -323,7 +464,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splices comments into the given data [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';
@@ -372,7 +513,6 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
                 continue;
             }
 
-            // Prune mode: remove all comments from the line [ds]
             if (mode === 'prune') {
                 if (lineAnalysis.isPureComment) {
                     finalDeletions.add(lineNum);
@@ -447,7 +587,6 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             const indentation = indentMatch ? indentMatch[1] : '';
 
             const commentLines = c.comment.split(/\r?\n/).map((line, idx) => {
-                // Add the comment to the list of comments [ds]
                 let trimmed = line.trimStart();
                 if (!trimmed) return '';
 
@@ -479,7 +618,6 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     const filteredText = filtered.map(line => line.text);
     const filteredIndices = filtered.map(line => line.originalIndex);
 
-    // Check if the filtered text is equal to the original text [ds]
     const textEqual = filteredText.every((text, idx) => {
         const origIdx = filteredIndices[idx];
         const originalLine = originalLines[origIdx];
@@ -518,7 +656,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Runs the CLI interface [ds] */
+/** Runs the CLI application [ds] */
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -662,7 +800,7 @@ Options:
     ];
     const allIgnored = [...defaultIgnoredFolders, ...userIgnorePatterns];
 
-    /** Checks if a given path is ignored [ds] */
+    /** Checks if a path is ignored based on the ignore patterns [ds] */
     function isPathIgnored(targetPath) {
         const filename = path.basename(targetPath);
         for (const pattern of allIgnored) {
@@ -673,7 +811,7 @@ Options:
         return false;
     }
 
-    /** Processes a given path [ds] */
+    /** Processes a given path, which can be a file or directory [ds] */
     async function processPath(targetPath) {
         const stats = fs.statSync(targetPath);
 

package/lib/config.js

@@ -4,7 +4,7 @@ const os = require('os');
 const readline = require('readline');
 const configPath = path.join(os.homedir(), '.devsplainrc');
 
-/** Prompts the user for a secret input, hiding the input from 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({
@@ -33,7 +33,7 @@ function askSecret(query) {
   });
 }
 
-/** Retrieves the configuration, either from environment variables or by prompting the user [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';
@@ -46,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 the configuration file does not exist or forceWizard is true, prompt the user to configure [ds]
   if (!fs.existsSync(configPath) || forceWizard) {
     let rl = readline.createInterface({
       input: process.stdin,
@@ -58,13 +58,13 @@ async function getConfig(forceWizard = false) {
     let config = null;
     let confirmed = false;
 
-    // Continuously prompt the user until the configuration is confirmed [ds]
+    // Keep prompting the user until they confirm their configuration settings. [ds]
     while (!confirmed) {
       let baseUrl = "";
       let model = "";
       let provider = "";
 
-      // Display the list 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)");
@@ -115,7 +115,7 @@ async function getConfig(forceWizard = false) {
         continue;
       }
 
-      // Prompt the user for an API key [ds]
+      // Get the API key from the user. [ds]
       let apiKey = '';
       while (true) {
         const promptMsg = provider === 'custom' 
@@ -142,7 +142,7 @@ async function getConfig(forceWizard = false) {
         console.log(`API key is required for provider '${provider}'.`);
       }
 
-      // Ask the user if they want to enable auto-pruning of existing comments [ds]
+      // 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();
@@ -156,7 +156,7 @@ async function getConfig(forceWizard = false) {
         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}`);
@@ -165,7 +165,7 @@ async function getConfig(forceWizard = false) {
       console.log(`Auto-Prune:   ${autoPrune ? 'Yes' : 'No'}`);
       console.log("-----------------------------\n");
 
-      // Confirm the configuration with the user [ds]
+      // 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') {
@@ -187,10 +187,9 @@ async function getConfig(forceWizard = false) {
 
     rl.close();
 
-    // Write the configuration to the config file [ds]
+    // Write the configuration settings to the config file. [ds]
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
     try {
-      // Set the permissions of the config file to prevent other users from reading it [ds]
       if (process.platform !== 'win32') {
         fs.chmodSync(configPath, 0o600);
       }
@@ -204,4 +203,5 @@ async function getConfig(forceWizard = false) {
   }
 }
 
+// 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.1",
+  "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",