devsplain 1.1.0 → 1.5.0

package/lib/llm.js

@@ -1,97 +1,222 @@
-/**
- * Asynchronously retrieves comments for a given piece of code.
- * 
- * @param {string} code The code for which to retrieve comments.
- * @param {string} language The programming language of the code.
- * @param {object} config An object containing configuration settings for the API request.
- * @param {string} [mode='default'] The mode in which to retrieve comments. Can be 'light', 'full', or 'default'.
- * @returns {Promise<string>} A promise that resolves to the commented code.
- */
-async function getComments(code, language, config, mode = 'default') {
-    // First, we need to determine the instruction based on the mode
-    let instruction = "Add JSDoc/docstrings block above functions. Do NOT add inline comments unless the logic is extremely complex or highly non-obvious. Keep the code clean and readable.";
-    // If the mode is 'light', we update the instruction accordingly
-    if (mode === 'light') {
-        instruction = "Add ONLY JSDoc/docstrings above functions. Do NOT add any inline comments inside the functions. Keep it extremely minimal.";
-    } 
-    // If the mode is 'full', we update the instruction to include detailed inline comments
-    else if (mode === 'full') {
-        instruction = "Add highly detailed JSDoc/docstrings above functions, and add detailed inline comments explaining almost every single line of logic.";
-    }
-    
-    // Now, we create a prompt based on the language and instruction
-    const prompt = `
-    // This is a prompt to add comments to the provided code
-    Add comments to this ${language} code. ${instruction}
-    // The commented code should be returned without any markdown, explanations, or personal messages
-    Return ONLY the commented code. NO MARKDOWN. NO EXPLANATION. NO PERSONAL MESSAGE.
-    ${code}
-    `;
-
-    // Next, we check the provider in the config to determine which API to use
-    if (config.provider === 'gemini') {
-        // If the provider is 'gemini', we use the Google API
-        const url = `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent?key=${config.apiKey}`;
-        // We make a POST request to the API with the prompt
-        const response = await fetch(url, {
-            method: 'POST',
-            // We set the content type to application/json
-            headers: { 'Content-Type': 'application/json' },
-            // We stringified the prompt as JSON
-            body: JSON.stringify({
-                "contents": [{ "parts": [{ "text": prompt }] }]
-            })
-        });
-        
-        // We parse the response as JSON
-        const data = await response.json();
-        // For debugging purposes, we log the API response
-        console.log("DEBUG API RESPONSE:", data);
-        
-        // If there's an error in the response, we log the error and exit the process
-        if (data.error) {
-            console.error("\n API Error:", data.error.message);
-            process.exit(1);
-        }
-        
-        // We extract the commented code from the response
-        let text = data.candidates[0].content.parts[0].text;
-        // We remove any unnecessary characters from the commented code
-        text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
-        // Finally, we return the commented code
-        return text;
-    } 
-    // If the provider is not 'gemini', we use a different API
-    else {
-        const url = `${config.baseUrl}/v1/chat/completions`;
-        // We make a POST request to the API with the prompt
-        const response = await fetch(url, {
-            method: 'POST',
-            // We set the content type to application/json and include the API key in the authorization header
-            headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${config.apiKey}` },
-            // We stringified the prompt as JSON
-            body: JSON.stringify({ "model": config.model, "messages": [{ "role": "user", "content": prompt }] })
-        });
-        
-        // We parse the response as JSON
-        const data = await response.json();
-        // For debugging purposes, we log the API response
-        console.log("DEBUG API RESPONSE:", data);
-        
-        // If there's an error in the response, we log the error and exit the process
-        if (data.error) {
-            console.error("\n API Error:", data.error.message);
-            process.exit(1);
-        }
-        
-        // We extract the commented code from the response
-        let text = data.choices[0].message.content;
-        // We remove any unnecessary characters from the commented code
-        text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
-        // Finally, we return the commented code
-        return text;
-    }
-}
-
-// We export the getComments function
+/**
+ * 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.
+*/
+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 {
+            const response = await fetch(url, {
+                ...options,
+                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 {
+                return response;
+            }
+        } catch (err) {
+            clearTimeout(timeoutId);
+            // Handle specific timeout case separately
+            if (err.name === 'AbortError') {
+                lastError = new Error("Request timed out after 15 seconds");
+            } else {
+                lastError = err;
+            }
+        }
+
+        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));
+        }
+    }
+    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).
+*/
+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');
+
+    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.";
+        }
+
+        prompt = `
+You are a code documentation engine. Analyze the following ${language} code which has line numbers prepended to it.
+${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 /** */).
+3. Do NOT include the original code in your response.
+4. If no comments are needed, return an empty array: [].
+
+Example Output:
+[
+  { "line": 4, "comment": "/** Calculates the total price */" },
+  { "line": 12, "comment": "// Check for null values" }
+]
+
+Here is the source code:
+${numberedCode}
+        `.trim();
+    }
+
+    let textResponse = "";
+
+    // Branching logic for different LLM providers
+    if (config.provider === 'gemini') {
+        const url = `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent?key=${config.apiKey}`;
+        let data;
+        try {
+            const response = await fetchWithRetry(url, {
+                method: 'POST',
+                headers: { 
+                    'Content-Type': 'application/json' 
+                },
+                body: JSON.stringify({
+                    "contents": [{ "parts": [{ "text": prompt }] }]
+                })
+            });
+            data = await response.json();
+        } catch (error) {
+            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+        }
+        if (data.error) {
+            throw new Error(`API Error: ${data.error.message}`);
+        }
+        textResponse = data.candidates[0].content.parts[0].text;
+    } 
+    else {
+        const url = `${config.baseUrl}/v1/chat/completions`;
+        let data;
+
+        try {
+            const response = await fetchWithRetry(url, {
+                method: 'POST',
+                headers: { 
+                    'Content-Type': 'application/json', 
+                    'Authorization': `Bearer ${config.apiKey}` 
+                },
+                body: JSON.stringify({ 
+                    "model": config.model, 
+                    "messages": [{ 
+                        "role": "user", 
+                        "content": prompt 
+                    }] 
+                })
+            });
+            data = await response.json();
+        } catch (error) {
+            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+        }
+        if (data.error) {
+            throw new Error(`API Error: ${data.error.message}`);
+        }
+        textResponse = data.choices[0].message.content;
+    }
+
+    // Extract JSON array from LLM response text
+    let cleanText = textResponse.trim();
+    const start = cleanText.indexOf('[');
+    const end = cleanText.lastIndexOf(']');
+    if (start !== -1 && end !== -1 && end >= start) {
+        cleanText = cleanText.substring(start, end + 1);
+    }
+
+    let parsed;
+    // Validate response format and schema integrity
+    try {
+        parsed = JSON.parse(cleanText);
+    } catch (e) {
+        throw new Error(`Parsing Error: Failed to parse LLM response as JSON. Raw response was:\n${textResponse}`);
+    }
+
+    if (!Array.isArray(parsed)) {
+        throw new Error("Schema Error: LLM response is not a JSON array.");
+    }
+
+    for (const item of parsed) {
+        if (typeof item !== 'object' || item === null) {
+            throw new Error("Schema Error: Array elements must be objects.");
+        }
+        if (!Number.isInteger(item.line) || item.line <= 0) {
+            throw new Error("Schema Error: 'line' must be a positive integer.");
+        }
+
+        if (mode === 'clean') {
+            if (item.action !== 'delete') {
+                throw new Error("Schema Error: 'action' must be 'delete' in clean mode.");
+            }
+        } else {
+            if (typeof item.comment !== 'string') {
+                throw new Error("Schema Error: 'comment' must be a string.");
+            }
+
+            const trimmedComment = item.comment.trim();
+            // Sanity check for valid comment syntax
+            const startsWithCommentMarker = 
+                trimmedComment.startsWith('//') || 
+                trimmedComment.startsWith('/*') || 
+                trimmedComment.startsWith('#') ||
+                trimmedComment.startsWith('<!--') ||
+                trimmedComment.startsWith('--');
+
+            if (!startsWithCommentMarker) {
+                throw new Error(`Security Error: Comment on line ${item.line} does not start with a valid comment character sequence. Rejected: ${trimmedComment}`);
+            }
+        }
+    }
+
+    return parsed;
+}
+
 module.exports = { getComments };

package/package.json

@@ -1,38 +1,43 @@
-{
-  "name": "devsplain",
-  "version": "1.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",
-  "main": "bin/cli.js",
-  "type": "commonjs",
-  "bin": {
-    "devsplain": "./bin/cli.js"
-  },
-  "files": [
-    "bin",
-    "lib"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "keywords": [
-    "cli",
-    "ai",
-    "comments",
-    "jsdoc",
-    "documentation",
-    "gemini",
-    "groq",
-    "llm"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mwahaj36/devsplain.git"},
-  "bugs": {
-  "url": "https://github.com/mwahaj36/devsplain/issues"  },
-"homepage": "https://github.com/mwahaj36/devsplain#readme",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
-}
+{
+  "name": "devsplain",
+  "version": "1.5.0",
+  "description": "An agent-agnostic CLI tool that automatically adds JSDoc and inline comments to your code using free LLMs.",
+  "author": "mwahaj36",
+  "license": "MIT",
+  "main": "bin/cli.js",
+  "type": "commonjs",
+  "bin": {
+    "devsplain": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "comments",
+    "jsdoc",
+    "documentation",
+    "gemini",
+    "groq",
+    "llm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mwahaj36/devsplain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mwahaj36/devsplain/issues"
+  },
+  "homepage": "https://github.com/mwahaj36/devsplain#readme",
+  "scripts": {
+    "test": "jest"
+  },
+  "devDependencies": {
+    "jest": "^30.4.2"
+  }
+}