devsplain 2.3.0 → 2.3.1

package/README.md

@@ -18,7 +18,7 @@ Unlike interactive AI editors, `devsplain` is designed for batch documentation p
 - **Comment Preservation & Tagging**: AI-generated comments are tagged with `[ds]`. Your manually written comments are safe and will never be touched by the engine.
 - **Local Deterministic Scrubber**: The `--clean` flag strips AI-generated `[ds]` comments locally using a deterministic lexical state machine—no LLM calls, API keys, or internet required.
 - **Git Hook Automation**: Supports an automated two-commit Git hook workflow (`pre-commit` for quality, `post-commit` for auto-generated documentation commits) that prevents recursive commit loops.
-- **Bring Your Own LLM**: Native setup wizard for Groq, Gemini, OpenAI, or any OpenAI-compatible API endpoint (like Ollama or LMStudio).
+- **Bring Your Own LLM**: Native setup wizard for Groq, Gemini, OpenAI, Claude, DeepSeek, or any OpenAI-compatible API endpoint (like Ollama or LMStudio).
 - **Exponential Backoff**: Resilient AI request handler that automatically retries rate-limited requests with exponential backoff.
 - **Headless & Override Control**: Configure via environment variables or override global config settings dynamically on the fly with command-line flags.
 
@@ -109,7 +109,7 @@ devsplain <file-or-directory> [options]
 | `--force` | Bypasses the safety block check that prevents running `devsplain` on a dirty Git working tree. |
 | `--clean` | Scrubber mode. Deterministically removes only devsplain-generated comments tagged with `[ds]`, preserving your manual comments. |
 | `--prune` | Destructive scrubber mode. Removes ALL comments and docstrings from source files, including your own manual comments. |
-| `--provider <name>`| Temporary one-off override for the AI provider (`gemini`, `groq`, `openai`, `custom`) for this command run only (does not modify the saved config file). |
+| `--provider <name>`| Temporary one-off override for the AI provider (`gemini`, `groq`, `openai`, `claude`, `deepseek`, `custom`) for this command run only (does not modify the saved config file). |
 | `--model <name>` | Temporary one-off override for the model name for this command run only. |
 | `--api-key <key>` | Temporary one-off override for the API key for this command run only. |
 | `--base-url <url>` | Temporary one-off override for the API base URL for this command run only. |

package/bin/cli.js

@@ -766,7 +766,7 @@ Options:
   --force             Bypass the dirty Git tree safety check
   --clean             Scrub only devsplain-generated [ds] comments
   --prune             Destructively scrub ALL comments from files
-  --provider <name>   Override AI provider (gemini, groq, openai, custom)
+  --provider <name>   Override AI provider (gemini, groq, openai, claude, deepseek, custom)
   --model <name>      Override AI model name
   --api-key <key>     Override API key for the provider
   --base-url <url>    Override base URL for custom APIs
@@ -862,10 +862,10 @@ Options:
     if (cliProvider) {
         config.provider = cliProvider;
         if (!cliModel) {
-            config.model = cliProvider === 'gemini' ? 'gemini-2.0-flash' : (cliProvider === 'claude' ? 'claude-3-5-sonnet-20240620' : 'llama-3.3-70b-versatile');
+            config.model = cliProvider === 'gemini' ? 'gemini-2.0-flash' : (cliProvider === 'claude' ? 'claude-3-5-sonnet-20240620' : (cliProvider === 'deepseek' ? 'deepseek-chat' : (cliProvider === 'openai' ? 'gpt-4o' : 'llama-3.3-70b-versatile')));
         }
         if (!cliBaseUrl) {
-            config.baseUrl = cliProvider === 'gemini' ? null : (cliProvider === 'groq' ? 'https://api.groq.com/openai' : (cliProvider === 'openai' ? 'https://api.openai.com' : (cliProvider === 'claude' ? 'https://api.anthropic.com' : '')));
+            config.baseUrl = cliProvider === 'gemini' ? null : (cliProvider === 'groq' ? 'https://api.groq.com/openai' : (cliProvider === 'openai' ? 'https://api.openai.com' : (cliProvider === 'claude' ? 'https://api.anthropic.com' : (cliProvider === 'deepseek' ? 'https://api.deepseek.com' : ''))));
         }
     }
     if (cliModel) config.model = cliModel;

package/lib/config.js

@@ -61,8 +61,24 @@ function migrateConfig(oldConfig) {
 async function getConfig(forceWizard = false) {
   if (process.env.DEVSPLAIN_API_KEY || process.env.DEVSPLAIN_PROVIDER) {
     const provider = process.env.DEVSPLAIN_PROVIDER || 'gemini';
-    const model = process.env.DEVSPLAIN_MODEL || (provider === 'gemini' ? 'gemini-2.0-flash' : (provider === 'claude' ? 'claude-3-5-sonnet-20240620' : 'llama-3.3-70b-versatile'));
-    const baseUrl = process.env.DEVSPLAIN_BASE_URL || (provider === 'gemini' ? null : (provider === 'claude' ? 'https://api.anthropic.com' : 'https://api.groq.com/openai'));
+    const model = process.env.DEVSPLAIN_MODEL || (
+      provider === 'gemini' ? 'gemini-2.0-flash' : (
+        provider === 'claude' ? 'claude-3-5-sonnet-20240620' : (
+          provider === 'deepseek' ? 'deepseek-chat' : (
+            provider === 'openai' ? 'gpt-4o' : 'llama-3.3-70b-versatile'
+          )
+        )
+      )
+    );
+    const baseUrl = process.env.DEVSPLAIN_BASE_URL || (
+      provider === 'gemini' ? null : (
+        provider === 'claude' ? 'https://api.anthropic.com' : (
+          provider === 'deepseek' ? 'https://api.deepseek.com' : (
+            provider === 'openai' ? 'https://api.openai.com' : 'https://api.groq.com/openai'
+          )
+        )
+      )
+    );
     return {
       provider,
       apiKey: process.env.DEVSPLAIN_API_KEY || '',
@@ -136,8 +152,9 @@ async function getConfig(forceWizard = false) {
           console.log("3. OpenAI (Paid)");
           console.log("4. Custom (Ollama, local, etc)");
           console.log("5. Claude (Anthropic)");
+          console.log("6. DeepSeek (deepseek-chat, deepseek-reasoner)");
 
-          const choice = await askQuestion("Select (1-5): ");
+          const choice = await askQuestion("Select (1-6): ");
 
           if (choice === '1') {
             provider = 'groq';
@@ -175,8 +192,14 @@ async function getConfig(forceWizard = false) {
             console.log("\nGet your Anthropic key here: https://console.anthropic.com/settings/keys");
             const customModel = await askQuestion("Model name (press Enter for default 'claude-3-5-sonnet-20240620'): ");
             model = customModel.trim() || 'claude-3-5-sonnet-20240620';
+          } else if (choice === '6') {
+            provider = 'deepseek';
+            baseUrl = 'https://api.deepseek.com';
+            console.log("\nGet your DeepSeek key here: https://platform.deepseek.com/api_keys");
+            const customModel = await askQuestion("Model name (press Enter for default 'deepseek-chat'): ");
+            model = customModel.trim() || 'deepseek-chat';
           } else {
-            console.log("Invalid choice. Please select 1, 2, 3, 4, or 5.");
+            console.log("Invalid choice. Please select 1, 2, 3, 4, 5, or 6.");
             continue;
           }
         } else {

package/lib/llm.js

@@ -90,38 +90,40 @@ async function runWithConcurrency(items, taskFn) {
 
     for (let i = 0; i < items.length; i++) {
         const item = items[i];
+
+        while (executing.size >= _concurrencyLimit) {
+            await Promise.race(executing);
+        }
+
         const task = (async () => {
-            try {
-                return await taskFn(item);
-            } catch (err) {
-                // On 429, downshift to serial and retry the item after backoff [ds]
-                if (err.isRateLimit) {
-                    if (!_hitRateLimit) {
-                        _hitRateLimit = true;
-                        _concurrencyLimit = 1;
-                        console.warn(`[devsplain] Rate limit hit — switching to serial mode.`);
-                    }
-                    // Wait for all in-flight tasks to settle before retrying [ds]
-                    await Promise.allSettled([...executing]);
-                    const backoff = 2000 + Math.random() * 1000;
-                    console.warn(`[devsplain] Backing off for ${Math.round(backoff)}ms...`);
-                    await new Promise(r => setTimeout(r, backoff));
+            const maxRetries = 3;
+            for (let attempt = 0; attempt < maxRetries; attempt++) {
+                try {
                     return await taskFn(item);
+                } catch (err) {
+                    if (err.isRateLimit && attempt < maxRetries - 1) {
+                        if (!_hitRateLimit) {
+                            _hitRateLimit = true;
+                            _concurrencyLimit = 1;
+                            console.warn(`[devsplain] Rate limit hit — switching to serial mode.`);
+                        }
+                        const backoff = (process.env.NODE_ENV === 'test' ? 50 : 2000) * Math.pow(2, attempt) + Math.random() * 500;
+                        console.warn(`[devsplain] Backing off for ${Math.round(backoff)}ms...`);
+                        await new Promise(r => setTimeout(r, backoff));
+                        continue;
+                    }
+                    throw err;
                 }
-                throw err;
             }
         })();
 
-        const tracked = task.then(
-            val => { executing.delete(tracked); return val; },
-            err => { executing.delete(tracked); throw err; }
-        );
+        let tracked;
+        tracked = task.finally(() => {
+            executing.delete(tracked);
+        });
+        tracked.catch(() => {});
         executing.add(tracked);
         results.push(tracked);
-
-        if (executing.size >= _concurrencyLimit) {
-            await Promise.race(executing);
-        }
     }
     return Promise.all(results);
 }
@@ -433,7 +435,7 @@ async function getComments(code, language, config, mode = 'default') {
     if (lines.length <= CHUNK_THRESHOLD) {
         const numberedCode = lines.map((line, i) => `${i + 1}: ${line}`).join('\n');
         const prompt = buildPrompt(numberedCode, language, mode);
-        const textResponse = await fetchFromProvider(prompt, config);
+        const [textResponse] = await runWithConcurrency([prompt], p => fetchFromProvider(p, config));
         return parseAndValidate(textResponse, mode);
     }
 

package/package.json

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