devsplain 2.1.0 → 2.1.1

package/bin/cli.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 let rl;
 let askQuestion;
 
-/** Checks if the Git repository has uncommitted changes [ds] */
+// Checks if the Git working tree is dirty [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;
 }
 
-/** Checks if a line of code 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());
@@ -116,49 +116,55 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
                         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;
+                    const isShellOrRuby = ['.sh', '.rb'].includes(ext.toLowerCase());
+                    if (isShellOrRuby) {
+                        if (line[j] === '#') {
+                            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;
                         }
-                    }
-                    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)) {
+                        if (ext.toLowerCase() === '.php' && 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 prefix = line.slice(0, k + 1);
-                                if (/(?:return|typeof|yield|await|throw)\s*$/.test(prefix)) {
+                                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 (isRegex) {
+                                inRegex = true;
+                                j++;
+                                continue;
+                            }
                         }
                     }
                 }
@@ -230,7 +236,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble || inCppRawString || inRegex;
 }
 
-/** Analyzes the comments in a given set of code lines [ds] */
+// Analyzes 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());
@@ -329,52 +335,59 @@ function analyzeComments(lines, ext = '') {
                         break;
                     }
                 } else {
-                    if (line.slice(j, j + 2) === '//') {
-                        commentStartIndex = j;
-                        break;
-                    }
-                    if (line.slice(j, j + 2) === '/*') {
-                        commentStartIndex = j;
-                        inBlockJS = true;
-                        blockDepthJS = 1;
-                        j += 2;
-                        continue;
-                    }
-                    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;
+                    const isShellOrRuby = ['.sh', '.rb'].includes(ext.toLowerCase());
+                    if (isShellOrRuby) {
+                        if (line[j] === '#') {
+                            commentStartIndex = j;
+                            break;
+                        }
+                    } else {
+                        if (line.slice(j, j + 2) === '//') {
+                            commentStartIndex = j;
+                            break;
+                        }
+                        if (line.slice(j, j + 2) === '/*') {
+                            commentStartIndex = j;
+                            inBlockJS = true;
+                            blockDepthJS = 1;
+                            j += 2;
                             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)) {
+                        if (ext.toLowerCase() === '.php' && 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 prefix = line.slice(0, k + 1);
-                                if (/(?:return|typeof|yield|await|throw)\s*$/.test(prefix)) {
+                                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 (isRegex) {
+                                inRegex = true;
+                                j++;
+                                continue;
+                            }
                         }
                     }
                 }
@@ -464,7 +477,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splices comments into the provided code data [ds] */
+// Splices comments into the given code data [ds]
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -656,7 +669,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Runs the CLI application [ds] */
+// Runs the CLI interface for the application [ds]
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -800,7 +813,6 @@ Options:
     ];
     const allIgnored = [...defaultIgnoredFolders, ...userIgnorePatterns];
 
-    /** 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) {
@@ -811,7 +823,7 @@ Options:
         return false;
     }
 
-    /** Processes a given path, which can be a file or directory [ds] */
+    // Processes a given file path, either a file or directory [ds]
     async function processPath(targetPath) {
         const stats = fs.statSync(targetPath);
 
@@ -869,6 +881,7 @@ Options:
                         fs.renameSync(tempPath, targetPath);
                         console.log(` Successfully saved ${targetPath}`);
                     } else {
+                        // Asks the user if they want to save the commented code to a file [ds]
                         console.log(` Skipped ${targetPath}`);
                     }
                 } else {
@@ -901,6 +914,7 @@ Options:
     rl.close();
 }
 
+// Starts the CLI application if this script is run directly [ds]
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/lib/llm.js

@@ -1,6 +1,7 @@
-/** Fetches a URL with retry functionality [ds] */
+// Asynchronously fetches data from the specified URL with a retry mechanism [ds]
 async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000) {
     let lastError;
+    // Loop through each attempt, up to the maximum number of retries [ds]
     for (let attempt = 0; attempt < maxRetries; attempt++) {
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 15000);
@@ -36,16 +37,44 @@ async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000)
     throw lastError;
 }
 
-/** Gets comments for the given code [ds] */
+// Retrieves comments for the given code, language, and configuration [ds]
 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 instruction = "Provide JSDoc/docstrings block comments above functions and sparse inline comments for complex logic.";
+    // Extract the file extension from the language string [ds]
+    const extMatch = language.match(/\.[0-9a-z]+$/i);
+    const ext = extMatch ? extMatch[0].toLowerCase() : '';
+    const isPython = ext === '.py';
+    const isRubyOrShell = ['.rb', '.sh', '.php'].includes(ext);
+    const isHTML = ['.html', '.vue', '.svelte'].includes(ext);
+    const isSql = ext === '.sql';
+    
+    // Define the single-line comment token and examples [ds]
+    let singleLineToken = '//';
+    let blockExample = '/** Calculates the total price */';
+    let inlineExample = '// Check for null values';
+
+    if (isPython || isRubyOrShell) {
+        singleLineToken = '#';
+        blockExample = '# Calculates the total price';
+        inlineExample = '# Check for null values';
+    } else if (isHTML) {
+        singleLineToken = '<!--';
+        blockExample = '<!-- Calculates the total price -->';
+        inlineExample = '<!-- Check for null values -->';
+    } else if (isSql) {
+        singleLineToken = '--';
+        blockExample = '-- Calculates the total price';
+        inlineExample = '-- Check for null values';
+    }
+
+    // Provide instructions based on the mode [ds]
+    let instruction = `Provide block comments above functions and sparse inline comments for complex logic.`;
     if (mode === 'light') {
-        instruction = "Provide ONLY JSDoc/docstrings above functions. Keep it minimal.";
+        instruction = `Provide ONLY block comments 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.";
+        instruction = `Provide highly detailed block comments above functions, and exhaustive step-by-step inline comments 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 prompt = `
@@ -54,24 +83,24 @@ ${instruction}
 
 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 where the comment should be inserted ABOVE) and "comment" (the text of the comment itself, including standard comment syntax like // or /** */).
+2. Each object must have exactly two properties: "line" (the integer line number where the comment should be inserted ABOVE) and "comment" (the text of the comment itself).
 3. Do NOT include the original code in your response.
 4. If no comments are needed, return an empty array: [].
+5. IMPORTANT: Use ONLY ${singleLineToken} for comments. DO NOT use docstrings or multi-line string literals like """ or ''' for comments.
 
 Example Output:
 [
-  { "line": 4, "comment": "/** Calculates the total price */" },
-  { "line": 12, "comment": "// Check for null values" }
+  { "line": 4, "comment": "${blockExample}" },
+  { "line": 12, "comment": "${inlineExample}" }
 ]
 
 Here is the source code:
 ${numberedCode}
     `.trim();
 
-    // Initialize text response [ds]
     let textResponse = "";
 
-    // Check if provider is Gemini [ds]
+    // Handle API requests based on the provider [ds]
     if (config.provider === 'gemini') {
         const url = `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent?key=${config.apiKey}`;
         let data;
@@ -94,6 +123,7 @@ ${numberedCode}
         }
         textResponse = data.candidates[0].content.parts[0].text;
     } else if (config.provider === 'claude') {
+        // Handle Claude API requests [ds]
         const url = `${config.baseUrl}/v1/messages`;
         let data;
         try {
@@ -122,7 +152,7 @@ ${numberedCode}
         }
         textResponse = data.content[0].text;
     } 
-    // Otherwise, use an OpenAI-compatible provider [ds]
+    // Handle other API requests [ds]
     else {
         const url = `${config.baseUrl}/v1/chat/completions`;
         let data;
@@ -152,7 +182,6 @@ ${numberedCode}
         textResponse = data.choices[0].message.content;
     }
 
-    // Clean up the text response [ds]
     let cleanText = textResponse.trim();
     const start = cleanText.indexOf('[');
     const end = cleanText.lastIndexOf(']');
@@ -160,9 +189,9 @@ ${numberedCode}
         cleanText = cleanText.substring(start, end + 1);
     }
 
-    // Parse the response as JSON [ds]
     let parsed;
     try {
+        // Attempt to parse the response as JSON [ds]
         parsed = JSON.parse(cleanText);
     } catch (e) {
         throw new Error(`Parsing Error: Failed to parse LLM response as JSON. Raw response was:\n${textResponse}`);

package/package.json

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