devsplain 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,81 @@
+# 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.
+
+## Installation
+
+Install it globally via npm:
+
+```bash
+npm install -g devsplain
+```
+
+## Usage
+
+Simply point `devsplain` at any file you want to comment:
+
+```bash
+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.
+
+**Usage Examples:**
+
+```bash
+devsplain src/utils.js --light
+devsplain src/ --full
+devsplain legacy_code.js --clean
+devsplain lib/ --dry-run
+```
+
+### Supported Languages
+
+Because `devsplain` uses LLMs, it natively understands almost every language syntax. It currently processes the following extensions:
+
+- **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)
+
+`devsplain` doesn't lock you into one ecosystem. On your first run, an interactive Setup Wizard will ask you which engine you want to use:
+
+1. **Groq** (Recommended) - Instant, free Llama-3 endpoints.
+2. **Gemini** - Google's free tier endpoints.
+3. **OpenAI** - Standard paid ChatGPT models.
+4. **Custom** - Point it at ANY OpenAI-compatible endpoint (e.g., local models via Ollama or LMStudio).
+
+_(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

@@ -1,59 +1,196 @@
 #!/usr/bin/env node
+
 /**
- * Requires the necessary modules for the script to run.
- * @requires ../lib/llm.js - provides the getComments function
- * @requires ../lib/config.js - provides the getConfig function
- * @requires fs - provides file system functionality
+ * Import required modules.
+ * @module llm
+ * @module config
+ * @module fs
+ * @module path
+ * @module readline
  */
-const { getComments } = require('../lib/llm.js')
-const { getConfig } = require('../lib/config.js')
+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 });
+
+/**
+ * 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 askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
 /**
- * Retrieves the file path from the command line arguments.
+ * Get the filepath and arguments from the command line.
  * @type {string}
  */
-const filepath = process.argv[2]
+const filepath = process.argv[2];
+const args = process.argv.slice(3);
+let mode = 'default';
 
 /**
- * Checks if a file path was provided.
- * If not, it logs the usage message and exits the process.
+ * 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, if not display usage information.
  */
 if (!filepath) {
-    console.log("usage: commie <file>")
-    process.exit(1)
-}
+    console.log("usage: devsplain <file-or-directory>");
+    process.exit(1);
+} 
+else if (!fs.existsSync(filepath)) {
+    console.log(`Error: The path '${filepath}' does not exist.`);
+    process.exit(1);
+} 
 else {
-    /**
-     * Defines an asynchronous function to comment the code in the provided file.
-     * @async
-     */
     (async () => {
         /**
-         * Retrieves the configuration settings.
+         * Get the configuration.
          * @type {object}
          */
         const config = await getConfig();
-        
+
         /**
-         * Reads the contents of the file at the provided file path.
-         * @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');
-        
-        // Log a message to indicate that the file is being analyzed
-        console.log("Analyzing File...");
-        
+        async function processPath(targetPath) {
+            /**
+             * Get the stats of the target path.
+             * @type {fs.Stats}
+             */
+            const stats = fs.statSync(targetPath);
+
+            /**
+             * 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'   
+                ];
+
+                /**
+                 * 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}`);
+                }
+            }
+        }
+
         /**
-         * Retrieves the commented code using the getComments function.
-         * @type {string}
+         * Start processing the provided filepath.
          */
-        const commentedCode = await getComments(data, 'javascript', config)
-        
-        // Write the commented code back to the file
-        fs.writeFileSync(filepath, commentedCode);
-        
-        // Log a success message with the file path
-        console.log(`Successfully commented ${filepath}`);
+        await processPath(filepath);
+        console.log("\n All done!");
     })();
 }

package/lib/config.js

@@ -1,36 +1,81 @@
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const readline = require('readline');
-const configPath = path.join(os.homedir(), '.commierc');
-
-const rl=readline.createInterface({
-            input:process.stdin,
-            output:process.stdout
-        });
-const askQuestion=(query)=>new Promise((resolve)=>rl.question(query,resolve))
-
-
-
-async function getConfig(){
-    if(!fs.existsSync(configPath)){
-        console.log("Please Enter your api key");
-        const answer=await askQuestion("Paste it here: ");
-        rl.close()
-           const config = {
-            provider: 'groq',
-            apiKey: answer,
-            model: 'llama-3.3-70b-versatile',
-            baseUrl: 'https://api.groq.com/openai'
-        };
-        fs.writeFileSync(configPath,JSON.stringify(config, null,2))
-        return config
-    }
-    else {
-    rl.close(); 
-    const rawData = fs.readFileSync(configPath, 'utf8');
-    return JSON.parse(rawData);
-    }
-}
-
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const configPath = path.join(os.homedir(), '.devsplainrc');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+/**
+ * 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 = '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') {
+      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') {
+      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();
+
+    const config = {
+      provider: provider,
+      apiKey: apiKey,
+      model: model,
+      baseUrl: baseUrl
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+    return config;
+  } else {
+    rl.close();
+
+    const rawData = fs.readFileSync(configPath, 'utf8');
+
+    return JSON.parse(rawData);
+  }
+}
+
 module.exports = { getConfig };

package/lib/llm.js

@@ -1,53 +1,140 @@
-async function getComments(code,language,config){
-    const prompt=
-    `
-    Add comments to this ${language} code. add JSDoc/docstrings block above functions and brief inline comments for complex logic. Return ONLY the commented code. NO MARKDOWN. NO EXPLANATION. NO PERSONAL MESSAGE.
-    ${code}
-    `
-
-    if(config.provider==='gemini'){
-        const url=`https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent?key=${config.apiKey}`;
-        const response = await fetch(url,
-            {
-                method:'POST',
-                headers:{'Content-Type':'application/json'},
-                body:JSON.stringify({
-                    "contents":[{"parts":[{"text":prompt}]}]
-                })
-            }
-        );
-        const data=await response.json();
-        console.log("DEBUG API RESPONSE:", data); 
-        if (data.error) {
-            console.error("\n API Error:", data.error.message);
-            process.exit(1);
-        }
-        let text = data.candidates[0].content.parts[0].text;
-        text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
-        return text;
-    }
-    else{
-        const url=`${config.baseUrl}/v1/chat/completions`;
-        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 }]
-            })
-
-        })
-        const data = await response.json();
-        console.log("DEBUG API RESPONSE:", data); 
-         if (data.error) {
-            console.error("\n API Error:", data.error.message);
-            process.exit(1);
-        }
-        let text = data.choices[0].message.content;
-        text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
-        return text;
-
-
-    }
-
-}
-
-module.exports={getComments};
+/**
+ * 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 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') {
+    // 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.";
+    
+    // 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.";
+    } 
+    // Check if the mode is 'full' and update the instruction accordingly
+    else if (mode === 'full') {
+        // 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.";
+    }
+    
+    // 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}
+        `;
+    }
+
+    // Check if the provider is 'gemini' and proceed accordingly
+    if (config.provider === 'gemini') {
+        // Construct the URL for the API request
+        const url = `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent?key=${config.apiKey}`;
+        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' 
+                },
+                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);
+        }
+        
+        // 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);
+        }
+        
+        // Extract the generated text from the API response
+        let text = data.candidates[0].content.parts[0].text;
+        // Remove any unnecessary code blocks and trim the text
+        text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
+        // Return the generated text
+        return text;
+    } 
+    // 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`;
+        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);
+        }
+        
+        // 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);
+        }
+        
+        // Extract the generated text from the API response
+        let text = data.choices[0].message.content;
+        // Remove any unnecessary code blocks and trim the text
+        text = text.replace(/^```[\w]*\n/m, '').replace(/```$/m, '').trim();
+        // Return the generated text
+        return text;
+    }
+}
+
+// Export the getComments function as a module
+module.exports = { getComments };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devsplain",
-  "version": "1.0.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,13 +28,16 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mwahaj36/commie.git"
+    "url": "git+https://github.com/mwahaj36/devsplain.git"
   },
   "bugs": {
-    "url": "https://github.com/mwahaj36/commie/issues"
+    "url": "https://github.com/mwahaj36/devsplain/issues"
   },
-  "homepage": "https://github.com/mwahaj36/commie#readme",
+  "homepage": "https://github.com/mwahaj36/devsplain#readme",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest"
+  },
+  "devDependencies": {
+    "jest": "^30.4.2"
   }
 }