devsplain 1.7.0 → 1.8.0

package/README.md

@@ -1,7 +1,10 @@
 # devsplain
+An agent-agnostic CLI tool that adds JSDoc and inline comments using state-of-the-art LLMs while preserving non-comment source lines byte-for-byte through deterministic verification.
 
-An industrial-grade, agent-agnostic CLI tool that automatically adds JSDoc and inline comments to your code using state-of-the-art LLMs, while guaranteeing code integrity with deterministic safety constraints.
+![devsplain demo](sample.gif)
 
+devsplain never rewrites executable code.
+If the original source cannot be reproduced exactly after comment insertion, the operation aborts.
 ---
 
 ## Key Features
@@ -35,6 +38,11 @@ Many AI code formatters rewrite your code entirely, exposing you to logic regres
 ### String Literal Guardrails
 The engine tracks lexical state across template strings, single quotes, double quotes, and multi-line docstrings (such as Python triple-quotes). Comment insertion is blocked if the target line resides within a string literal, preventing broken syntax.
 
+### The `[ds]` AI Tag Guarantee
+Every single comment generated by the LLM is forcibly prefixed with a `[ds]` tag (e.g., `// [ds] This function handles...`). 
+This guarantees that the local `devsplain` lexer can mathematically differentiate between your human-written manual comments and the AI-generated comments. 
+When you run the `--clean` command, the lexer looks specifically for the `[ds]` prefix and surgically removes only the AI-generated comments, safely preserving 100% of your manual documentation.
+
 ### Why Not AST Verification?
 
 AST verification would require language-specific parser dependencies for every supported language.
@@ -75,6 +83,9 @@ devsplain --config
 
 Your settings are stored securely in `~/.devsplainrc` (configured with `chmod 600` on POSIX systems to restrict read access).
 
+> [!NOTE]
+> **API Testing Notice:** `devsplain` supports OpenAI, Anthropic, Ollama, Groq, and Gemini endpoints, but the E2E test suite has currently only been aggressively verified against the **Groq** and **Gemini** APIs. If you encounter any unexpected parsing issues or edge-case errors with other providers, please open an issue or submit a PR!
+
 ---
 
 ## CLI Usage & Options

package/bin/cli.js

@@ -566,10 +566,10 @@ Options:
     if (cliProvider) {
         config.provider = cliProvider;
         if (!cliModel) {
-            config.model = cliProvider === 'gemini' ? 'gemini-2.0-flash' : 'llama-3.3-70b-versatile';
+            config.model = cliProvider === 'gemini' ? 'gemini-2.0-flash' : (cliProvider === 'claude' ? 'claude-3-5-sonnet-20240620' : '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' : ''));
+            config.baseUrl = cliProvider === 'gemini' ? null : (cliProvider === 'groq' ? 'https://api.groq.com/openai' : (cliProvider === 'openai' ? 'https://api.openai.com' : (cliProvider === 'claude' ? 'https://api.anthropic.com' : '')));
         }
     }
     if (cliModel) config.model = cliModel;

package/bin/post-commit.js

@@ -3,51 +3,69 @@ const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
 
-/** Attempts to execute the post-commit hook [ds] */
+/** Main execution block [ds] */
 try {
-    // Get the last commit message [ds]
+    // Allow users to completely bypass the AI hook using an environment variable [ds]
+    if (process.env.SKIP_DEVSPLAIN) {
+        console.log('[devsplain] SKIP_DEVSPLAIN is set. Bypassing AI generation.');
+        process.exit(0);
+    }
+
+    // Prevent the hook from firing during rebases, merges, or cherry-picks [ds]
+    const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+    const isRebasing = fs.existsSync(path.join(gitDir, 'rebase-merge')) || fs.existsSync(path.join(gitDir, 'rebase-apply'));
+    const isMerging = fs.existsSync(path.join(gitDir, 'MERGE_HEAD'));
+    const isCherryPicking = fs.existsSync(path.join(gitDir, 'CHERRY_PICK_HEAD'));
+
+    if (isRebasing || isMerging || isCherryPicking) {
+        console.log('[devsplain] Skipping AI comment generation during git rebase/merge/cherry-pick to avoid history conflicts.');
+        process.exit(0);
+    }
+
+    /** Check if the current operation is a rebase, merge or cherry-pick [ds] */
     const lastCommitMsg = execSync('git log -1 --format=%s', { encoding: 'utf8' }).trim();
     if (lastCommitMsg === 'docs: auto-generated comments by devsplain') {
         process.exit(0);
     }
 
-    // Get the list of changed files in the last commit [ds]
+    // Get the last commit message [ds]
     const changedFilesStr = execSync('git diff-tree --no-commit-id --name-only -r HEAD', { encoding: 'utf8' }).trim();
     if (!changedFilesStr) {
         process.exit(0);
     }
     const changedFiles = changedFilesStr.split(/\r?\n/);
 
-    /** Defines a list of valid file extensions for commenting [ds] */
+    /** List of valid file extensions for commenting [ds] */
     const validExtensions = [
         '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
         '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs',
         '.swift', '.kt', '.dart', '.sh'
     ];
 
-    /** Filters the changed files based on valid extensions and existence [ds] */
+    /** Filter files to be commented [ds] */
     const filesToComment = changedFiles.filter(file => {
         const ext = path.extname(file).toLowerCase();
         const isIgnored = file.includes('node_modules/') || file.includes('tests/') || file.includes('__tests__/') || file.includes('fixtures/');
         return validExtensions.includes(ext) && fs.existsSync(file) && !isIgnored;
     });
 
+    // Check if there are any files to comment [ds]
     if (filesToComment.length === 0) {
         process.exit(0);
     }
 
-    // Log the number of files to be commented [ds]
     console.log(`[devsplain] Found ${filesToComment.length} file(s) in the last commit to auto-comment.`);
 
-    // Parse command-line arguments for commenting mode [ds]
+    // Parse command line arguments for mode flag [ds]
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
     if (args.includes('--full')) modeFlag = ' --full';
 
     let commentedAny = false;
+    const successfullyCommentedFiles = [];
 
-    /** Iterates through the files to be commented and attempts to comment each one [ds] */
+    /** Iterate over files to comment [ds] */
     for (const file of filesToComment) {
         try {
             const ext = path.extname(file).toLowerCase();
@@ -61,7 +79,7 @@ try {
             } catch (prevErr) {
             }
 
-            // Check if the file has been modified beyond just comments [ds]
+            // Compare file content before and after the last commit [ds]
             if (contentPrev) {
                 const cleanHead = spliceComments(contentHead, [], 'prune', ext);
                 const cleanPrev = spliceComments(contentPrev, [], 'prune', ext);
@@ -73,26 +91,36 @@ try {
         } catch (cleanErr) {
         }
 
-        // Attempt to comment the file using the cli script [ds]
+        // Comment the file using the CLI [ds]
         console.log(`[devsplain] Automatically commenting file: ${file}`);
         try {
             const cliPath = path.join(__dirname, 'cli.js');
             execSync(`node "${cliPath}" "${file}" --force${modeFlag}`, { stdio: 'inherit' });
             commentedAny = true;
+            successfullyCommentedFiles.push(file);
         } catch (err) {
             console.warn(`[devsplain] Warning: Failed to comment ${file}: ${err.message}`);
         }
     }
 
-    /** If any files were commented, stage and commit the changes [ds] */
+    /** Stage and commit auto-generated comments if any [ds] */
     if (commentedAny) {
-        const status = execSync('git diff --name-only', { encoding: 'utf8' }).trim();
-        if (status.length > 0) {
+        // Only stage the exact files that the AI touched to avoid accidentally committing unstaged work [ds]
+        for (const file of successfullyCommentedFiles) {
+            try {
+                execSync(`git add "${file}"`);
+            } catch (addErr) {}
+        }
+        
+        // Check if there are actually staged changes now [ds]
+        const stagedChanges = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim();
+        if (stagedChanges.length > 0) {
             console.log('[devsplain] Staging and committing auto-generated comments...');
-            execSync('git commit -am "docs: auto-generated comments by devsplain" --no-verify', { stdio: 'inherit' });
+            execSync('git commit -m "docs: auto-generated comments by devsplain" --no-verify', { stdio: 'inherit' });
             console.log('[devsplain] Comments committed successfully! Rollback via: git reset --hard HEAD~1');
         }
     }
+/** Catch and log any errors [ds] */
 } catch (e) {
     console.warn(`[devsplain] Warning: post-commit hook script failed: ${e.message}`);
 }

package/lib/config.js

@@ -8,8 +8,8 @@ const configPath = path.join(os.homedir(), '.devsplainrc');
 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' : 'llama-3.3-70b-versatile');
-    const baseUrl = process.env.DEVSPLAIN_BASE_URL || (provider === 'gemini' ? null : 'https://api.groq.com/openai');
+    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'));
     return {
       provider,
       apiKey: process.env.DEVSPLAIN_API_KEY || '',
@@ -41,9 +41,10 @@ async function getConfig(forceWizard = false) {
       console.log("2. Gemini (Free Tier)");
       console.log("3. OpenAI (Paid)");
       console.log("4. Custom (Ollama, local, etc)");
+      console.log("5. Claude (Anthropic)");
 
       // Get user's selected AI provider option [ds]
-      const choice = await askQuestion("Select (1-4): ");
+      const choice = await askQuestion("Select (1-5): ");
 
       // Handle selected AI provider option [ds]
       if (choice === '1') {
@@ -68,8 +69,14 @@ async function getConfig(forceWizard = false) {
         provider = 'custom';
         model = await askQuestion("Model name (e.g., llama3): ");
         baseUrl = await askQuestion("Base URL (e.g., http://localhost:11434): ");
+      } else if (choice === '5') {
+        provider = 'claude';
+        baseUrl = 'https://api.anthropic.com';
+        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 {
-        console.log("Invalid choice. Please select 1, 2, 3, or 4.");
+        console.log("Invalid choice. Please select 1, 2, 3, 4, or 5.");
         continue;
       }
 

package/lib/llm.js

@@ -117,8 +117,36 @@ ${numberedCode}
             throw new Error(`API Error: ${data.error.message}`);
         }
         textResponse = data.candidates[0].content.parts[0].text;
+    } else if (config.provider === 'claude') {
+        const url = `${config.baseUrl}/v1/messages`;
+        let data;
+        try {
+            const response = await fetchWithRetry(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': config.apiKey,
+                    'anthropic-version': '2023-06-01'
+                },
+                body: JSON.stringify({
+                    "model": config.model,
+                    "max_tokens": 8192,
+                    "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.content[0].text;
     } 
-    // Otherwise, use a different provider [ds]
+    // Otherwise, use an OpenAI-compatible provider [ds]
     else {
         const url = `${config.baseUrl}/v1/chat/completions`;
         let data;

package/package.json

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