devsplain 1.2.0 → 1.5.1

package/bin/post-commit.js

@@ -0,0 +1,96 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { spliceComments } = require('./cli');
+
+// Wrap logic in try-catch to prevent blocking the git commit process on failure
+try {
+    const lastCommitMsg = execSync('git log -1 --format=%s', { encoding: 'utf8' }).trim();
+    // Avoid infinite loops if this hook triggered the current commit
+    if (lastCommitMsg === 'docs: auto-generated comments by devsplain') {
+        process.exit(0);
+    }
+
+    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/);
+
+    // Define supported file extensions for auto-documentation
+    const validExtensions = [
+        '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
+        '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs',
+        '.swift', '.kt', '.dart', '.sh'
+    ];
+
+    // Filter changed files to include only supported extensions that currently exist
+    const filesToComment = changedFiles.filter(file => {
+        const ext = path.extname(file).toLowerCase();
+        return validExtensions.includes(ext) && fs.existsSync(file);
+    });
+
+    if (filesToComment.length === 0) {
+        process.exit(0);
+    }
+
+    console.log(`[devsplain] Found ${filesToComment.length} file(s) in the last commit to auto-comment.`);
+
+    const args = process.argv.slice(2);
+    let modeFlag = '';
+    if (args.includes('--light')) modeFlag = ' --light';
+    if (args.includes('--full')) modeFlag = ' --full';
+
+    let commentedAny = false;
+
+    // Iterate through each changed file to check if content actually changed
+    for (const file of filesToComment) {
+        try {
+            const ext = path.extname(file).toLowerCase();
+            // Retrieve current file content from filesystem
+            const contentHead = fs.readFileSync(file, 'utf8');
+            let contentPrev = '';
+            // Attempt to fetch the version of the file from the previous commit for comparison
+            try {
+                contentPrev = execSync(`git show HEAD~1:"${file}"`, { 
+                    encoding: 'utf8', 
+                    stdio: ['ignore', 'pipe', 'ignore'] 
+                });
+            } catch (prevErr) {
+            }
+
+            if (contentPrev) {
+                // Strip existing comments to determine if the logic changed or just documentation
+                const cleanHead = spliceComments(contentHead, [], 'clean', ext);
+                const cleanPrev = spliceComments(contentPrev, [], 'clean', ext);
+                if (cleanHead === cleanPrev) {
+                    console.log(`[devsplain] Skipping ${file}: commit contains only comment changes.`);
+                    continue;
+                }
+            }
+        } catch (cleanErr) {
+        }
+
+        console.log(`[devsplain] Automatically commenting file: ${file}`);
+        try {
+            // Invoke the CLI tool to generate comments for the changed file
+            execSync(`node bin/cli.js "${file}" --force${modeFlag}`, { stdio: 'inherit' });
+            commentedAny = true;
+        } catch (err) {
+            console.warn(`[devsplain] Warning: Failed to comment ${file}: ${err.message}`);
+        }
+    }
+
+    // If changes were made, stage and commit them automatically to the current branch
+    if (commentedAny) {
+        const status = execSync('git diff --name-only', { encoding: 'utf8' }).trim();
+        if (status.length > 0) {
+            console.log('[devsplain] Staging and committing auto-generated comments...');
+            // Use --no-verify to prevent triggering this hook recursively during the commit
+            execSync('git commit -am "docs: auto-generated comments by devsplain" --no-verify', { stdio: 'inherit' });
+            console.log('[devsplain] Comments committed successfully! Rollback via: git reset --hard HEAD~1');
+        }
+    }
+} catch (e) {
+    console.warn(`[devsplain] Warning: post-commit hook script failed: ${e.message}`);
+}

package/bin/setup-hook.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const readline = require('readline');
+
+/**
+ * Configures and installs git pre-commit and post-commit hooks.
+ * Detects the local git repository and prompts the user for comment mode preferences.
+*/
+async function installHooks() {
+    try {
+        // Resolve the actual .git directory path
+        const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+        const hooksDir = path.join(gitDir, 'hooks');
+        if (!fs.existsSync(hooksDir)) {
+            fs.mkdirSync(hooksDir, { recursive: true });
+        }
+
+        let modeChoice = '1';
+        // Check if running in an interactive terminal to prompt for preferences
+        if (process.stdout.isTTY) {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout
+            });
+            // Helper to wrap readline as a Promise for async/await control flow
+            const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+            console.log('\nSelect default commenting mode for Git commits:');
+            console.log('1. Balanced (mix of JSDoc and sparse inline comments)');
+            console.log('2. Light (JSDoc block comments above functions only)');
+            console.log('3. Full (aggressive inline commenting)');
+            const answer = await askQuestion('Select (1-3, default: 1): ');
+            modeChoice = answer.trim() || '1';
+            rl.close();
+        }
+
+        // Map user selection to CLI argument flags for the post-commit handler
+        let modeArgs = '';
+        if (modeChoice === '2') {
+            modeArgs = ' --light';
+        } else if (modeChoice === '3') {
+            modeArgs = ' --full';
+        }
+
+        // Define and write the pre-commit shell script
+        const preCommitHookPath = path.join(hooksDir, 'pre-commit');
+        const preCommitContent = `#!/bin/sh
+# devsplain native pre-commit hook
+echo "Running pre-commit tests..."
+npm test || exit 1
+`;
+        fs.writeFileSync(preCommitHookPath, preCommitContent);
+        // Ensure the shell script is executable by the system
+        try {
+            fs.chmodSync(preCommitHookPath, 0o755);
+        } catch (err) {}
+
+        // Define and write the post-commit shell script
+        const postCommitHookPath = path.join(hooksDir, 'post-commit');
+        const postCommitContent = `#!/bin/sh
+# devsplain native post-commit hook
+echo "Auto-generating comments for files in the last commit..."
+node bin/post-commit.js${modeArgs} || exit 1
+`;
+        fs.writeFileSync(postCommitHookPath, postCommitContent);
+        // Ensure the post-commit shell script is executable
+        try {
+            fs.chmodSync(postCommitHookPath, 0o755);
+        } catch (err) {}
+
+        console.log('Success: Native Git pre-commit and post-commit hooks installed successfully!');
+    } catch (e) {
+        console.warn('Warning: Could not set up Git hooks (not inside a git repository or git command missing).');
+    }
+}
+
+// Execute the hook installation sequence
+installHooks();

package/lib/config.js

@@ -1,81 +1,125 @@
-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);
-  }
-}
-
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const configPath = path.join(os.homedir(), '.devsplainrc');
+
+/**
+ * Retrieves configuration from environment variables or a local config file.
+ * Runs a setup wizard if configuration is missing or forced.
+ * @param {boolean} forceWizard - Whether to force the interactive setup.
+ * @returns {Promise<Object>} The configuration object.
+*/
+async function getConfig(forceWizard = false) {
+  // Priority 1: Check environment variables for configuration
+  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');
+    return {
+      provider,
+      apiKey: process.env.DEVSPLAIN_API_KEY || '',
+      model,
+      baseUrl
+    };
+  }
+
+  // Priority 2: Check for existing config file or run setup wizard
+  if (!fs.existsSync(configPath) || forceWizard) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    // Promisify readline to allow async flow
+    const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+    let config = null;
+    let confirmed = false;
+
+    // Loop until user confirms configuration choices
+    while (!confirmed) {
+      let baseUrl = "";
+      let model = "";
+      let provider = "";
+
+      console.log("\nWhich 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): ");
+
+      // Handle specific provider setup logic
+      if (choice === '1') {
+        provider = 'groq';
+        baseUrl = 'https://api.groq.com/openai';
+        console.log("\nGet your free Groq key here: https://console.groq.com/keys");
+        const customModel = await askQuestion("Model name (press Enter for default 'llama-3.3-70b-versatile'): ");
+        model = customModel.trim() || 'llama-3.3-70b-versatile';
+      } else if (choice === '2') {
+        provider = 'gemini';
+        baseUrl = null;
+        console.log("\nGet your free Gemini key here: https://aistudio.google.com/apikey");
+        const customModel = await askQuestion("Model name (press Enter for default 'gemini-2.0-flash'): ");
+        model = customModel.trim() || 'gemini-2.0-flash';
+      } else if (choice === '3') {
+        provider = 'openai';
+        baseUrl = 'https://api.openai.com';
+        console.log("\nGet your OpenAI key here: https://platform.openai.com/api-keys");
+        const customModel = await askQuestion("Model name (press Enter for default 'gpt-4o'): ");
+        model = customModel.trim() || 'gpt-4o';
+      } else if (choice === '4') {
+        provider = 'custom';
+        model = await askQuestion("Model name (e.g., llama3): ");
+        baseUrl = await askQuestion("Base URL (e.g., http://localhost:11434): ");
+      } else {
+        console.log("Invalid choice. Please select 1, 2, 3, or 4.");
+        continue;
+      }
+
+      const apiKey = await askQuestion("Paste your API key (leave blank for local models): ");
+
+      console.log("\n--- Configuration Summary ---");
+      console.log(`Provider: ${provider}`);
+      console.log(`Model:    ${model}`);
+      console.log(`Base URL: ${baseUrl || 'N/A'}`);
+      // Mask API key for security in display
+      console.log(`API Key:  ${apiKey ? apiKey.substring(0, 4) + '*'.repeat(Math.max(0, apiKey.length - 4)) : 'None'}`);
+      console.log("-----------------------------\n");
+
+      const confirm = await askQuestion("Does this look correct? (y/n, default: y): ");
+      if (confirm.toLowerCase() === 'y' || confirm.trim() === '') {
+        config = {
+          provider,
+          apiKey,
+          model,
+          baseUrl
+        };
+        confirmed = true;
+      } else {
+        console.log("Let's restart the configuration setup.");
+      }
+    }
+
+    rl.close();
+
+    // Save finalized config to home directory
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    try {
+      // Ensure config file is not readable by other users (POSIX only)
+      if (process.platform !== 'win32') {
+        fs.chmodSync(configPath, 0o600);
+      }
+    } catch (chmodErr) {
+    }
+
+    return config;
+  } else {
+    // Priority 3: Load from existing file
+    const rawData = fs.readFileSync(configPath, 'utf8');
+    return JSON.parse(rawData);
+  }
+}
+
 module.exports = { getConfig };