devsplain 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,58 @@
+# devsplain
+
+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
+```
+
+### 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.
+- **(Default)**: A balanced mix of JSDoc headers and sparse inline comments for complex logic.
+
+Example:
+
+```bash
+devsplain src/utils.js --light
+```
+
+### Samples in this Repository
+
+To see exactly what `devsplain` can do, the source code of this very repository was commented using the tool itself (using the Groq provider):
+
+- `bin/cli.js`: Commented using the **Default** mode.
+- `lib/config.js`: Commented using the **--light** mode.
+- `lib/llm.js`: Commented using the **--full** mode.
+
+## 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)._
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,59 +1,77 @@
 #!/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 - Provides functionality for getting comments.
+ * @module config - Provides functionality for getting configuration.
+ * @module fs - Provides functionality for interacting with the file system.
  */
-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');
 
 /**
- * Retrieves the file path from the command line arguments.
+ * Get the filepath from the command line arguments.
  * @type {string}
  */
-const filepath = process.argv[2]
+const filepath = process.argv[2];
+
+/**
+ * Get additional command line arguments.
+ * @type {array}
+ */
+const args = process.argv.slice(3);
+
+/**
+ * Set the default mode.
+ * @type {string}
+ */
+let mode = 'default';
+
+/**
+ * Check for mode flags in the command line arguments and update the mode accordingly.
+ */
+if (args.includes('--light')) mode = 'light';
+if (args.includes('--full')) mode = 'full';
 
 /**
- * Checks if a file path was provided.
- * If not, it logs the usage message and exits the process.
+ * Check if a filepath was provided.
  */
 if (!filepath) {
-    console.log("usage: commie <file>")
-    process.exit(1)
-}
-else {
+    console.log("usage: devsplain <file>");
+    process.exit(1);
+} else {
     /**
-     * Defines an asynchronous function to comment the code in the provided file.
+     * Main execution block.
      * @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.
+         * Read the file at the specified filepath.
          * @type {string}
          */
         const data = fs.readFileSync(filepath, 'utf-8');
-        
-        // Log a message to indicate that the file is being analyzed
+
         console.log("Analyzing File...");
-        
+        console.log(`Analyzing File in ${mode} mode...`);
+
         /**
-         * Retrieves the commented code using the getComments function.
+         * Get comments for the code in the file.
          * @type {string}
          */
-        const commentedCode = await getComments(data, 'javascript', config)
-        
-        // Write the commented code back to the file
+        const commentedCode = await getComments(data, 'javascript', config, mode);
+
+        /**
+         * 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}`);
     })();
 }

package/lib/config.js

@@ -1,36 +1,70 @@
-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
+});
+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.
+ */
+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,97 @@
-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};
+/**
+ * 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
+module.exports = { getComments };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devsplain",
-  "version": "1.0.0",
+  "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",
@@ -28,12 +28,10 @@
   ],
   "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"
-  },
-  "homepage": "https://github.com/mwahaj36/commie#readme",
+  "url": "https://github.com/mwahaj36/devsplain/issues"  },
+"homepage": "https://github.com/mwahaj36/devsplain#readme",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   }