devsplain 1.1.0 → 1.2.0

package/README.md

@@ -1,5 +1,7 @@
 # devsplain
 
+![devsplain demo](sample.gif)
+
 An agent-agnostic CLI tool that automatically adds JSDoc and inline comments to your code using free LLMs.
 
 Tired of writing documentation? Let AI do the explaining for you. `devsplain` reads your code and intelligently injects standard JSDoc headers and inline comments.
@@ -20,27 +22,42 @@ Simply point `devsplain` at any file you want to comment:
 devsplain src/utils.js
 ```
 
+### Directory Support (Bulk Processing)
+
+You don't have to go file-by-file! Point `devsplain` at an entire directory, and it will recursively crawl through your codebase and comment everything.
+
+```bash
+devsplain src/
+```
+
+_Note: `devsplain` is smart. It automatically ignores junk folders like `node_modules`, `.git`, `dist`, `venv`, and `.next` to save you time and API tokens._
+
 ### Modes
 
 You can control exactly how aggressive the AI is with its comments using flags:
 
 - `--light`: Only adds JSDoc blocks above functions. Keeps the inside of your functions completely untouched.
 - `--full`: Highly aggressive. Explains complex logic line-by-line inside your functions.
+- `--clean`: A code scrubber. Removes ALL existing comments from the code, leaving it completely bare.
+- `--dry-run`: Interactive preview. Prints the AI's output to the terminal and waits for your approval before saving to the file. Extremely safe for testing!
 - **(Default)**: A balanced mix of JSDoc headers and sparse inline comments for complex logic.
 
-Example:
+**Usage Examples:**
 
 ```bash
 devsplain src/utils.js --light
+devsplain src/ --full
+devsplain legacy_code.js --clean
+devsplain lib/ --dry-run
 ```
 
-### Samples in this Repository
+### Supported Languages
 
-To see exactly what `devsplain` can do, the source code of this very repository was commented using the tool itself (using the Groq provider):
+Because `devsplain` uses LLMs, it natively understands almost every language syntax. It currently processes the following extensions:
 
-- `bin/cli.js`: Commented using the **Default** mode.
-- `lib/config.js`: Commented using the **--light** mode.
-- `lib/llm.js`: Commented using the **--full** mode.
+- **Web**: `.js`, `.jsx`, `.ts`, `.tsx`, `.html`, `.css`, `.scss`, `.vue`, `.svelte`
+- **Backend**: `.py`, `.java`, `.c`, `.cpp`, `.cs`, `.go`, `.rb`, `.php`, `.rs`
+- **Mobile/Scripts**: `.swift`, `.kt`, `.dart`, `.sh`
 
 ## Agent Agnostic (Bring Your Own LLM)
 
@@ -53,6 +70,12 @@ To see exactly what `devsplain` can do, the source code of this very repository
 
 _(Your configuration is safely stored in `~/.devsplainrc` on your machine)._
 
+---
+
+### Disclaimer
+
+**Use at your own risk.** `devsplain` uses AI to physically overwrite your source files. While the prompts are heavily engineered to prevent code refactoring or corruption, AI is non-deterministic. **Always ensure your code is committed to Git (Version Control) before running `devsplain` on an entire directory!** We are not responsible for corrupted or lost code.
+
 ## License
 
 MIT

package/bin/cli.js

@@ -2,49 +2,55 @@
 
 /**
  * Import required modules.
- * @module llm - Provides functionality for getting comments.
- * @module config - Provides functionality for getting configuration.
- * @module fs - Provides functionality for interacting with the file system.
+ * @module llm
+ * @module config
+ * @module fs
+ * @module path
+ * @module readline
  */
 const { getComments } = require('../lib/llm.js');
 const { getConfig } = require('../lib/config.js');
 const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
 /**
- * Get the filepath from the command line arguments.
- * @type {string}
- */
-const filepath = process.argv[2];
-
-/**
- * Get additional command line arguments.
- * @type {array}
+ * Asks a question and returns the answer as a promise.
+ * @param {string} query - The question to be asked.
+ * @returns {Promise<string>} The answer to the question.
  */
-const args = process.argv.slice(3);
+const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
 /**
- * Set the default mode.
+ * Get the filepath and arguments from the command line.
  * @type {string}
  */
+const filepath = process.argv[2];
+const args = process.argv.slice(3);
 let mode = 'default';
 
 /**
- * Check for mode flags in the command line arguments and update the mode accordingly.
+ * Determine the mode based on the command line arguments.
+ * Supported modes are: 'light', 'full', and 'clean'.
  */
 if (args.includes('--light')) mode = 'light';
 if (args.includes('--full')) mode = 'full';
+if (args.includes('--clean')) mode = 'clean';
+const isDryRun = args.includes('--dry-run');
 
 /**
- * Check if a filepath was provided.
+ * Check if a filepath was provided, if not display usage information.
  */
 if (!filepath) {
-    console.log("usage: devsplain <file>");
+    console.log("usage: devsplain <file-or-directory>");
     process.exit(1);
-} else {
-    /**
-     * Main execution block.
-     * @async
-     */
+} 
+else if (!fs.existsSync(filepath)) {
+    console.log(`Error: The path '${filepath}' does not exist.`);
+    process.exit(1);
+} 
+else {
     (async () => {
         /**
          * Get the configuration.
@@ -53,25 +59,138 @@ if (!filepath) {
         const config = await getConfig();
 
         /**
-         * Read the file at the specified filepath.
-         * @type {string}
+         * Process a path, either a file or directory.
+         * @param {string} targetPath - The path to process.
+         * @returns {Promise<void>}
          */
-        const data = fs.readFileSync(filepath, 'utf-8');
+        async function processPath(targetPath) {
+            /**
+             * Get the stats of the target path.
+             * @type {fs.Stats}
+             */
+            const stats = fs.statSync(targetPath);
 
-        console.log("Analyzing File...");
-        console.log(`Analyzing File in ${mode} mode...`);
+            /**
+             * If the target path is a directory, process its contents.
+             */
+            if (stats.isDirectory()) {
+                const folderName = path.basename(targetPath);
+                /**
+                 * List of ignored folders.
+                 * @type {string[]}
+                 */
+                const ignoredFolders = [
+                    'node_modules', '.git', 'dist', 'build', 'out', 
+                    '.next', '.nuxt', '.svelte-kit', 
+                    'venv', 'env', '.venv',          
+                    '.vscode', '.idea', 'coverage'   
+                ];
 
-        /**
-         * Get comments for the code in the file.
-         * @type {string}
-         */
-        const commentedCode = await getComments(data, 'javascript', config, mode);
+                /**
+                 * Check if the folder should be ignored.
+                 */
+                if (ignoredFolders.includes(folderName)) {
+                    // Folder will be skipped
+                    return;
+                }
+
+                console.log(`\n Scanning directory: ${targetPath}`);
+                /**
+                 * Read the contents of the directory.
+                 * @type {string[]}
+                 */
+                const items = fs.readdirSync(targetPath);
+                
+                /**
+                 * Process each item in the directory.
+                 */
+                for (const item of items) {
+                    const fullPath = path.join(targetPath, item);
+                    await processPath(fullPath); 
+                }
+            } 
+            /**
+             * If the target path is a file, process it.
+             */
+            else if (stats.isFile()) {
+                /**
+                 * Get the file extension.
+                 * @type {string}
+                 */
+                const ext = path.extname(targetPath).toLowerCase();
+                /**
+                 * List of valid file extensions.
+                 * @type {string[]}
+                 */
+                const validExtensions = [
+                    '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
+                    '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs', 
+                    '.swift', '.kt', '.dart', '.sh'
+                ];
+
+                /**
+                 * Check if the file extension is valid.
+                 */
+                if (!validExtensions.includes(ext)) {
+                    // File type is not supported, skipping
+                    return;
+                }
+
+                const filename = path.basename(targetPath);
+                /**
+                 * Read the file contents.
+                 * @type {string}
+                 */
+                const data = fs.readFileSync(targetPath, 'utf-8');
+                
+                /**
+                 * Check if the file is empty.
+                 */
+                if (data.trim() === '') {
+                    console.log(` Skipping ${filename} (Empty File)`);
+                    return;
+                }
+
+                console.log(` Analyzing ${filename} in ${mode} mode...`);
+                /**
+                 * Get the commented code.
+                 * @type {string}
+                 */
+                const commentedCode = await getComments(data, filename, config, mode);
+                
+                /**
+                 * If in dry run mode, display a preview of the commented code.
+                 */
+                if (isDryRun) {
+                    console.log(`\n --- DRY RUN PREVIEW: ${filename} ---`);
+                    console.log(commentedCode);
+                    console.log(`---------------------------------------\n`);
+                    
+                    /**
+                     * Ask the user if they want to save the commented code.
+                     */
+                    const answer = await askQuestion("Type 'write' to save to file, or press any key to discard ");
+                    
+                    if (answer.toLowerCase() == 'write') {
+                        fs.writeFileSync(targetPath, commentedCode);
+                        console.log(` Successfully saved ${targetPath}`);
+                    } else {
+                        console.log(` Skipped ${targetPath}`);
+                    }
+                } else {
+                    /**
+                     * Write the commented code to the file.
+                     */
+                    fs.writeFileSync(targetPath, commentedCode);
+                    console.log(` Successfully commented ${targetPath}`);
+                }
+            }
+        }
 
         /**
-         * Write the commented code back to the file.
+         * Start processing the provided filepath.
          */
-        fs.writeFileSync(filepath, commentedCode);
-
-        console.log(`Successfully commented ${filepath}`);
+        await processPath(filepath);
+        console.log("\n All done!");
     })();
 }

package/lib/config.js

@@ -8,61 +8,72 @@ const rl = readline.createInterface({
   input: process.stdin,
   output: process.stdout
 });
-const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve))
 
 /**
- * Retrieves the configuration for the application.
- * If the configuration file does not exist, it will prompt the user to create one.
- * @returns {Promise<Object>} The configuration object.
+ * Asks a question via the readline interface.
+ * @param {string} query 
+ * @returns {Promise<string>} 
+ */
+const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+/**
+ * Retrieves the configuration, creating a new one if it does not exist.
+ * @returns {Promise<Object>} 
  */
 async function getConfig() {
   if (!fs.existsSync(configPath)) {
     let baseUrl = "";
     let model = "";
     let provider = "";
+
     console.log("Which AI Provider Do You want to use?");
     console.log("1. Groq (Free, Fast, Llama-3)");
     console.log("2. Gemini (Free Tier)");
     console.log("3. OpenAI (Paid)");
     console.log("4. Custom (Ollama, local, etc)");
+
     const choice = await askQuestion("Select (1-4): ");
+
     if (choice === '1') {
-      provider = 'groq',
-        model = 'llama-3.3-70b-versatile',
-        baseUrl = 'https://api.groq.com/openai',
-        console.log("\nGet your free Groq key here: https://console.groq.com/keys")
-    }
-    else if (choice === '2') {
+      provider = 'groq';
+      model = 'llama-3.3-70b-versatile';
+      baseUrl = 'https://api.groq.com/openai';
+      console.log("\nGet your free Groq key here: https://console.groq.com/keys");
+    } else if (choice === '2') {
       provider = 'gemini';
       model = 'gemini-2.0-flash';
       baseUrl = null;
-      console.log("\nGet your free Gemini key here: https://aistudio.google.com/apikey")
-    }
-    else if (choice === '3') {
+      console.log("\nGet your free Gemini key here: https://aistudio.google.com/apikey");
+    } else if (choice === '3') {
       provider = 'openai';
       model = 'gpt-4o';
       baseUrl = 'https://api.openai.com';
-      console.log("\nGet your OpenAI key here: https://platform.openai.com/api-keys")
-    }
-    else if (choice === '4') {
+      console.log("\nGet your OpenAI key here: https://platform.openai.com/api-keys");
+    } else if (choice === '4') {
       provider = 'custom';
       model = await askQuestion("Model name (e.g., llama3): ");
       baseUrl = await askQuestion("Base URL (e.g., http://localhost:11434): ");
     }
+
     const apiKey = await askQuestion("Paste your API key (leave blank for local models): ");
-    rl.close()
+
+    rl.close();
+
     const config = {
       provider: provider,
       apiKey: apiKey,
       model: model,
       baseUrl: baseUrl
     };
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2))
-    return config
-  }
-  else {
+
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+    return config;
+  } else {
     rl.close();
+
     const rawData = fs.readFileSync(configPath, 'utf8');
+
     return JSON.parse(rawData);
   }
 }

package/lib/llm.js

@@ -1,97 +1,140 @@
 /**
- * Asynchronously retrieves comments for a given piece of code.
+ * This function generates commented code based on the given parameters.
+ * It sends a request to the specified AI provider with the provided code, language, and configuration.
+ * The function returns the commented code as a string.
  * 
- * @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.
+ * @param {string} code - The code that needs to be commented.
+ * @param {string} language - The programming language of the code.
+ * @param {object} config - The configuration object containing the provider and API details.
+ * @param {string} [mode='default'] - The mode of commenting. Default modes are 'default', 'light', 'full', and 'clean'.
+ * @returns {Promise<string>} The commented code.
  */
 async function getComments(code, language, config, mode = 'default') {
-    // First, we need to determine the instruction based on the mode
+    // Initialize 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
+    
+    // Check if the mode is 'light' and update the instruction accordingly
     if (mode === 'light') {
+        // In 'light' mode, only JSDoc comments are added above functions
         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
+    // Check if the mode is 'full' and update the instruction accordingly
     else if (mode === 'full') {
-        instruction = "Add highly detailed JSDoc/docstrings above functions, and add detailed inline comments explaining almost every single line of logic.";
+        // In 'full' mode, detailed JSDoc comments and inline comments are added
+        instruction = "Add highly detailed JSDoc/docstrings above functions, and add detailed inline comments explaining almost every single line of logic. Do NOT add comments inside string literals, template literals, or multiline strings.";
+    }
+    // Check if the mode is 'clean' and update the instruction accordingly
+    else if (mode === 'clean') {
+        // In 'clean' mode, all comments are removed from the code
+        instruction = "Remove ALL comments (both block/JSDoc and inline comments) from this code. Return only the raw, uncommented code. Do NOT alter the code logic or formatting.";
     }
     
-    // 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}
-    `;
+    // Initialize the prompt based on the mode
+    let prompt = "";
+    // Check if the mode is 'clean' and update the prompt accordingly
+    if (mode === 'clean') {
+        // In 'clean' mode, the prompt asks to remove all comments
+        prompt = `
+        Remove ALL comments (both block/JSDoc and inline comments) from the following ${language} code. 
+        Return ONLY the raw, uncommented code. NO MARKDOWN. NO EXPLANATION. NO PERSONAL MESSAGE.
+        Do NOT alter the code logic or formatting in any way.
+        ${code}
+        `;
+    } else {
+        // In other modes, the prompt asks to add comments to the code
+        prompt = `
+        Add comments to the code in this file (${language}). ${instruction}
+        If the code already contains comments, completely REPLACE them with your own. Do not leave duplicate or messy comments behind.
+        Return ONLY the commented code. NO MARKDOWN. NO EXPLANATION. NO PERSONAL MESSAGE.
+        Do NOT alter, refactor, or format the existing code in any way. Only add comments. IF ANYTHING WRONG HIGHLIGHT IN COMMENT BUT DO NOT CHANGE
+        ${code}
+        `;
+    }
 
-    // Next, we check the provider in the config to determine which API to use
+    // Check if the provider is 'gemini' and proceed accordingly
     if (config.provider === 'gemini') {
-        // If the provider is 'gemini', we use the Google API
+        // Construct the URL for the API request
         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 }] }]
-            })
-        });
+        let data;
         
-        // 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);
+        try {
+            // Send a POST request to the API with the prompt
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 
+                    'Content-Type': 'application/json' 
+                },
+                body: JSON.stringify({
+                    "contents": [{ "parts": [{ "text": prompt }] }]
+                })
+            });
+            // Parse the response as JSON
+            data = await response.json();
+        } catch (error) {
+            // Log any network errors and exit the process
+            console.log("\n Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            process.exit(1);
+        }
         
-        // If there's an error in the response, we log the error and exit the process
+        // Check if there is an error in the API response
         if (data.error) {
+            // Log the API error and exit the process
             console.error("\n API Error:", data.error.message);
             process.exit(1);
         }
         
-        // We extract the commented code from the response
+        // Extract the generated text from the API response
         let text = data.candidates[0].content.parts[0].text;
-        // We remove any unnecessary characters from the commented code
+        // Remove any unnecessary code blocks and trim the text
         text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
-        // Finally, we return the commented code
+        // Return the generated text
         return text;
     } 
-    // If the provider is not 'gemini', we use a different API
+    // If the provider is not 'gemini', proceed with the default API request
     else {
+        // Construct the URL for the API request
         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);
+        let data;
+
+        try {
+            // Send a POST request to the API with the prompt
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 
+                    'Content-Type': 'application/json', 
+                    'Authorization': `Bearer ${config.apiKey}` 
+                },
+                body: JSON.stringify({ 
+                    "model": config.model, 
+                    "messages": [{ 
+                        "role": "user", 
+                        "content": prompt 
+                    }] 
+                })
+            });
+            // Parse the response as JSON
+            data = await response.json();
+        } catch (error) {
+            // Log any network errors and exit the process
+            console.log("\n Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            process.exit(1);
+        }
         
-        // If there's an error in the response, we log the error and exit the process
+        // Check if there is an error in the API response
         if (data.error) {
+            // Log the API error and exit the process
             console.error("\n API Error:", data.error.message);
             process.exit(1);
         }
         
-        // We extract the commented code from the response
+        // Extract the generated text from the API response
         let text = data.choices[0].message.content;
-        // We remove any unnecessary characters from the commented code
+        // Remove any unnecessary code blocks and trim the text
         text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
-        // Finally, we return the commented code
+        // Return the generated text
         return text;
     }
 }
 
-// We export the getComments function
+// Export the getComments function as a module
 module.exports = { getComments };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devsplain",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "An agent-agnostic CLI tool that automatically adds JSDoc and inline comments to your code using free LLMs.",
   "author": "mwahaj36",
   "license": "MIT",
@@ -28,11 +28,16 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mwahaj36/devsplain.git"},
+    "url": "git+https://github.com/mwahaj36/devsplain.git"
+  },
   "bugs": {
-  "url": "https://github.com/mwahaj36/devsplain/issues"  },
-"homepage": "https://github.com/mwahaj36/devsplain#readme",
+    "url": "https://github.com/mwahaj36/devsplain/issues"
+  },
+  "homepage": "https://github.com/mwahaj36/devsplain#readme",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest"
+  },
+  "devDependencies": {
+    "jest": "^30.4.2"
   }
 }