devsplain 1.8.0 → 2.0.1

package/README.md

@@ -1,16 +1,20 @@
 # 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.
+
+**devsplain never rewrites executable code**—it's a single-shot CLI that adds JSDoc and inline comments across 22 languages using LLMs, preserving non-comment source lines byte-for-byte through deterministic verification.
 
 ![devsplain demo](sample.gif)
 
-devsplain never rewrites executable code.
-If the original source cannot be reproduced exactly after comment insertion, the operation aborts.
+Unlike interactive AI editors, `devsplain` is designed for batch documentation passes, CI pipelines, and git hook automation—no agent overhead, no per-file confirmation loops.
+
+> [!TIP]
+> **Built with devsplain**
+> This entire repository is heavily "dogfooded". Every single AI-generated `[ds]` comment you see in the source code of this tool was automatically generated and committed by `devsplain` itself using its native git hooks!
 ---
 
 ## Key Features
 
 - **Deterministic Code Integrity Verification**: Uses an index-preserving splicing engine. Your non-comment source lines are guaranteed to remain byte-for-byte identical after comment insertion.
-- **Multi-Language support**: Natively parses JavaScript, JSX, TypeScript, TSX, HTML, CSS, SCSS, Vue, Svelte, Python, Java, C, C++, C#, Go, Ruby, PHP, Rust, Swift, Kotlin, Dart, and Shell scripts.
+- **Multi-Language support**: Works across JavaScript, JSX, TypeScript, TSX, HTML, CSS, SCSS, Vue, Svelte, Python, Java, C, C++, C#, Go, Ruby, PHP, Rust, Swift, Kotlin, Dart, and Shell scripts.
 - **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.
@@ -40,14 +44,14 @@ The engine tracks lexical state across template strings, single quotes, double q
 
 ### 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. 
+This guarantees that the local `devsplain` lexer can lexically distinguish 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.
+AST parsers are language-specific. Supporting 22 languages would require 22 native parser dependencies, which defeats the zero-dependency architecture entirely.
 
-`devsplain` instead uses deterministic source-preservation verification:
+The line-splicing + round-trip diff approach achieves equivalent guarantees without any of that bloat. This is not a compromise—it's the right answer for this tool's constraints:
 
 1. Original source is loaded.
 2. Comments are inserted.
@@ -81,10 +85,10 @@ To force re-run the configuration wizard at any time, execute:
 devsplain --config
 ```
 
-Your settings are stored securely in `~/.devsplainrc` (configured with `chmod 600` on POSIX systems to restrict read access).
+Your settings are stored securely in `~/.devsplainrc` (configured with `chmod 600` on POSIX systems to restrict read access, and keystrokes are masked during input).
 
-> [!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!
+> [!CAUTION]
+> **Security Note:** Prefer configuring the `DEVSPLAIN_API_KEY` environment variable over using the `--api-key` CLI flag for recurring use. CLI flags may be exposed in your shell history (`~/.bash_history`) and process lists.
 
 ---
 
@@ -133,13 +137,10 @@ devsplain lib/ --prune
 devsplain src/utils.ts --provider gemini --model gemini-2.0-flash --api-key YOUR_KEY
 ```
 
-> [!WARNING]
-> **Directory Traversal Caution**
-> The built-in list of ignored folders (like `node_modules`, `.git`, `dist`, etc.) is not exhaustive. If you run `devsplain` on a broad directory that contains unignored directories (such as local caches or build directories), it may start commenting unwanted files in random folders.
-> 
-> To prevent this, it is highly recommended to either:
-> 1. Use the **Automated Git Hooks** to comment only on files modified in your commits.
-> 2. Pass specific files or selective subfolders manually (e.g., `devsplain src/utils.ts`) instead of targeting broad directories.
+> [!TIP]
+> **Directory Traversal Protection**
+> When you run `devsplain` on a directory, it automatically ignores common build/dependency folders (`node_modules`, `.git`, `dist`, etc.).
+> To ignore custom directories, simply create a `.devsplainignore` file in your project root using the standard `.gitignore` syntax. (A default `.devsplainignore` is automatically generated when you run `--setup-hook`).
 
 ---
 
@@ -168,6 +169,25 @@ Run the hook setup command inside your Git repository:
 devsplain --setup-hook
 ```
 
+### Bypassing the Hook (Manual Override)
+If you ever want to commit code without triggering the AI (for example, if you just ran `devsplain index.js --full` manually and want to freeze those specific comments without the background hook overwriting them), you can bypass the hook entirely:
+```bash
+SKIP_DEVSPLAIN=1 git commit -m "my commit message"
+```
+
+### Forcing or Skipping Auto-Prune
+(If `autoPrune: true` is set in your `~/.devsplainrc` via the `--config` wizard, the hook scrubs all existing comments before regenerating them.)
+
+If you want to change this behavior for a specific commit:
+- To **force an overwrite** (destroying all human/AI comments before generating new ones) regardless of your config:
+  ```bash
+  DS_OVER=1 git commit -m "overwrite docs"
+  ```
+- To **force preservation** of existing comments (overriding a global prune preference):
+  ```bash
+  DS_KEEP=1 git commit -m "keep docs"
+  ```
+
 ### Pipeline Architecture
 1. **Pre-commit Hook**: Runs your project test suite (`npm test`). If the tests fail, the commit is blocked.
 2. **Post-commit Hook**: 
@@ -179,6 +199,13 @@ devsplain --setup-hook
 
 ---
 
+## Known Limitations & Contributing
+
+> [!NOTE]
+> **API Testing Notice:** `devsplain` natively 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!
+
+---
+
 ## License
 
 This project is licensed under the MIT License.

package/bin/cli.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 let rl;
 let askQuestion;
 
-/** Checks if the current Git repository has uncommitted changes [ds] */
+/** Checks if the Git repository is dirty [ds] */
 function isGitDirty() {
     try {
         const gitDir = execSync('git rev-parse --is-inside-work-tree', { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim();
@@ -23,47 +23,109 @@ function isGitDirty() {
     return false;
 }
 
-/** Checks if a given line index is inside a string in a list of code lines [ds] */
+/** Checks if a line of code is inside a string [ds] */
 function isLineInsideString(lines, targetLineIndex, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
+    const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
     let inBacktick = false;
     let inTripleDouble = false;
     let inTripleSingle = false;
     let inSingle = false;
     let inDouble = false;
-
+    let inBlockJS = false;
+    let inBlockHTML = false;
     for (let i = 0; i < targetLineIndex; i++) {
         const line = lines[i];
         let j = 0;
         while (j < line.length) {
+            if (inBlockJS) {
+                if (line.slice(j, j + 2) === '*/') {
+                    inBlockJS = false;
+                    j += 2;
+                    continue;
+                }
+                j++;
+                continue;
+            }
+            if (inBlockHTML) {
+                if (line.slice(j, j + 3) === '-->') {
+                    inBlockHTML = false;
+                    j += 3;
+                    continue;
+                }
+                j++;
+                continue;
+            }
+            // Check if comment starts (skip processing quotes if we are entering a comment)
+            if (!inSingle && !inDouble && !inBacktick && !inTripleSingle && !inTripleDouble) {
+                if (isPython) {
+                    if (line[j] === '#') {
+                        break; // Ignore rest of line
+                    }
+                } else if (isHTML) {
+                    if (line.slice(j, j + 4) === '<!--') {
+                        inBlockHTML = true;
+                        // Check if current character is a backtick [ds]
+                        j += 4;
+                        continue;
+                    }
+                    if (line.slice(j, j + 2) === '/*') {
+                        inBlockJS = true;
+                        j += 2;
+                        continue;
+                    }
+                    if (line.slice(j, j + 2) === '//') {
+                        break; // Ignore rest of line
+                    }
+                } else {
+                    if (line.slice(j, j + 2) === '//') {
+                        break; // Ignore rest of line
+                    }
+                    if (line.slice(j, j + 2) === '/*') {
+                        inBlockJS = true;
+                        j += 2;
+                        continue;
+                    }
+                    const isShellOrRuby = ['.sh', '.rb', '.php'].includes(ext.toLowerCase());
+                    if (isShellOrRuby && line[j] === '#') {
+                        break; // Ignore rest of line
+                    }
+                }
+            }
             if (isPython) {
-                if (!inTripleSingle) {
+                if (!inTripleSingle && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === '"""') {
                         inTripleDouble = !inTripleDouble;
                         j += 3;
                         continue;
                     }
                 }
-                if (!inTripleDouble) {
+                if (!inTripleDouble && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === "'''") {
                         inTripleSingle = !inTripleSingle;
                         j += 3;
                         continue;
                     }
                 }
-            } else {
-                if (!inSingle && !inDouble && line[j] === '`') {
-                    let escaped = false;
-                    let k = j - 1;
-                    while (k >= 0 && line[k] === '\\') {
-                        escaped = !escaped;
-                        k--;
-                    }
-                    if (!escaped) {
-                        inBacktick = !inBacktick;
+            }
+            if (!inTripleSingle && !inTripleDouble) {
+                if (!isPython) {
+                    if (!inSingle && !inDouble) {
+                        if (line[j] === '`') {
+                        let escaped = false;
+                        let k = j - 1;
+                        while (k >= 0 && line[k] === '\\') {
+                            escaped = !escaped;
+                            k--;
+                        }
+                        if (!escaped) {
+                            inBacktick = !inBacktick;
+                        }
                     }
                 }
+                }
                 if (!inBacktick) {
+                    // Check if current character is a double quote [ds]
                     if (line[j] === '"' && !inSingle) {
                         let escaped = false;
                         let k = j - 1;
@@ -89,7 +151,8 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
             }
             j++;
         }
-        if (!isPython) {
+        const resetsAtLineEnd = ['.js', '.jsx', '.ts', '.tsx', '.java', '.c', '.cpp', '.cs', '.go', '.swift', '.kt', '.dart'].includes(ext.toLowerCase());
+        if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
         }
@@ -97,7 +160,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
 }
 
-/** Analyzes comments in a list of code lines [ds] */
+/** Analyzes comments in a given list of lines [ds] */
 function analyzeComments(lines, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
@@ -133,23 +196,12 @@ function analyzeComments(lines, ext = '') {
                 j++;
                 continue;
             }
-            // Check for comment start index in non-Python files [ds]
             if (!inSingle && !inDouble && !inBacktick && !inTripleSingle && !inTripleDouble) {
                 if (isPython) {
                     if (line[j] === '#') {
                         commentStartIndex = j;
                         break;
                     }
-                    if (line.slice(j, j + 2) === '/*') {
-                        commentStartIndex = j;
-                        inBlockJS = true;
-                        j += 2;
-                        continue;
-                    }
-                    if (line.slice(j, j + 2) === '//') {
-                        commentStartIndex = j;
-                        break;
-                    }
                 } else if (isHTML) {
                     if (line.slice(j, j + 4) === '<!--') {
                         commentStartIndex = j;
@@ -178,31 +230,33 @@ function analyzeComments(lines, ext = '') {
                         j += 2;
                         continue;
                     }
-                    if (line[j] === '#') {
+                    const isShellOrRuby = ['.sh', '.rb', '.php'].includes(ext.toLowerCase());
+                    if (isShellOrRuby && line[j] === '#') {
                         commentStartIndex = j;
                         break;
                     }
                 }
             }
             if (isPython) {
-                if (!inTripleSingle) {
+                if (!inTripleSingle && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === '"""') {
                         inTripleDouble = !inTripleDouble;
                         j += 3;
                         continue;
                     }
                 }
-                if (!inTripleDouble) {
+                if (!inTripleDouble && !inSingle && !inDouble) {
                     if (line.slice(j, j + 3) === "'''") {
                         inTripleSingle = !inTripleSingle;
                         j += 3;
                         continue;
                     }
                 }
-            // Check for string literals in non-Python files [ds]
-            } else {
-                if (!inSingle && !inDouble) {
-                    if (line[j] === '`') {
+            }
+            if (!inTripleSingle && !inTripleDouble) {
+                if (!isPython) {
+                    if (!inSingle && !inDouble) {
+                        if (line[j] === '`') {
                         let escaped = false;
                         let k = j - 1;
                         while (k >= 0 && line[k] === '\\') {
@@ -214,6 +268,7 @@ function analyzeComments(lines, ext = '') {
                         }
                     }
                 }
+                }
                 if (!inBacktick) {
                     if (line[j] === '"' && !inSingle) {
                         let escaped = false;
@@ -226,6 +281,7 @@ function analyzeComments(lines, ext = '') {
                             inDouble = !inDouble;
                         }
                     }
+                    // Check if current character is a single quote [ds]
                     else if (line[j] === "'" && !inDouble) {
                         let escaped = false;
                         let k = j - 1;
@@ -239,10 +295,10 @@ function analyzeComments(lines, ext = '') {
                     }
                 }
             }
-            // Increment character index [ds]
             j++;
         }
-        if (!isPython) {
+        const resetsAtLineEnd = ['.js', '.jsx', '.ts', '.tsx', '.java', '.c', '.cpp', '.cs', '.go', '.swift', '.kt', '.dart'].includes(ext.toLowerCase());
+        if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
         }
@@ -267,7 +323,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splices comments into a list of code lines [ds] */
+/** Splices comments into the given data [ds] */
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -289,7 +345,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
                     let start = i;
                     let end = i;
                     while (end < originalLines.length && analysis[end].isInsideBlock) end++;
-                    let blockStart = start - 1;
+                    let blockStart = Math.max(0, start - 1);
                     let blockEnd = end - 1;
                     let hasDs = false;
                     for (let k = blockStart; k <= blockEnd; k++) {
@@ -316,6 +372,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
                 continue;
             }
 
+            // Prune mode: remove all comments from the line [ds]
             if (mode === 'prune') {
                 if (lineAnalysis.isPureComment) {
                     finalDeletions.add(lineNum);
@@ -390,6 +447,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             const indentation = indentMatch ? indentMatch[1] : '';
 
             const commentLines = c.comment.split(/\r?\n/).map((line, idx) => {
+                // Add the comment to the list of comments [ds]
                 let trimmed = line.trimStart();
                 if (!trimmed) return '';
 
@@ -421,6 +479,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     const filteredText = filtered.map(line => line.text);
     const filteredIndices = filtered.map(line => line.originalIndex);
 
+    // Check if the filtered text is equal to the original text [ds]
     const textEqual = filteredText.every((text, idx) => {
         const origIdx = filteredIndices[idx];
         const originalLine = originalLines[origIdx];
@@ -459,7 +518,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Runs the CLI interface for the commenting tool [ds] */
+/** Runs the CLI interface [ds] */
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -549,6 +608,8 @@ Options:
     if (args.includes('--prune')) mode = 'prune';
     const isDryRun = args.includes('--dry-run');
     const isForce = args.includes('--force');
+    const hasOverwriteFlag = args.includes('--overwrite');
+    const hasKeepFlag = args.includes('--keep');
 
     if (process.env.NODE_ENV !== 'test' && isGitDirty() && !isForce) {
         console.error("Error: Git working tree is dirty. Please commit or stash your changes, or use --force to bypass this check.");
@@ -579,24 +640,48 @@ Options:
     let successCount = 0;
     let failCount = 0;
 
+    const isOverwrite = (hasOverwriteFlag || config.autoPrune) && !hasKeepFlag;
+
+    let userIgnorePatterns = [];
+    try {
+        const ignorePath = path.join(process.cwd(), '.devsplainignore');
+        if (fs.existsSync(ignorePath)) {
+            const ignoreContent = fs.readFileSync(ignorePath, 'utf8');
+            userIgnorePatterns = ignoreContent.split(/\r?\n/)
+                .map(line => line.trim())
+                .filter(line => line && !line.startsWith('#'));
+        }
+    } catch(e) {}
+
+    const defaultIgnoredFolders = [
+        'node_modules', '.git', 'dist', 'build', 'out', 
+        '.next', '.nuxt', '.svelte-kit', 
+        'venv', 'env', '.venv',          
+        '.vscode', '.idea', 'coverage',
+        'tests', '__tests__', 'fixtures'
+    ];
+    const allIgnored = [...defaultIgnoredFolders, ...userIgnorePatterns];
+
+    /** Checks if a given path is ignored [ds] */
+    function isPathIgnored(targetPath) {
+        const filename = path.basename(targetPath);
+        for (const pattern of allIgnored) {
+            const cleanPattern = pattern.replace(/\/$/, '').replace(/\\$/, '');
+            if (filename === cleanPattern) return true;
+            if (pattern.startsWith('*') && filename.endsWith(pattern.slice(1))) return true;
+        }
+        return false;
+    }
+
+    /** Processes a given path [ds] */
     async function processPath(targetPath) {
-        // Process a directory or file path [ds]
         const stats = fs.statSync(targetPath);
 
-        if (stats.isDirectory()) {
-            const folderName = path.basename(targetPath);
-            const ignoredFolders = [
-                'node_modules', '.git', 'dist', 'build', 'out', 
-                '.next', '.nuxt', '.svelte-kit', 
-                'venv', 'env', '.venv',          
-                '.vscode', '.idea', 'coverage',
-                'tests', '__tests__', 'fixtures'
-            ];
-
-            if (ignoredFolders.includes(folderName)) {
-                return;
-            }
+        if (isPathIgnored(targetPath)) {
+            return;
+        }
 
+        if (stats.isDirectory()) {
             console.log(`\n Scanning directory: ${targetPath}`);
             const items = fs.readdirSync(targetPath);
             for (const item of items) {
@@ -628,7 +713,8 @@ Options:
                 let comments = [];
                 let commentedCode;
                 if (mode !== 'clean' && mode !== 'prune') {
-                    const cleanData = spliceComments(data, [], 'clean', ext);
+                    const preProcessMode = isOverwrite ? 'prune' : 'clean';
+                    const cleanData = spliceComments(data, [], preProcessMode, ext);
                     comments = await getComments(cleanData, filename, config, mode);
                     commentedCode = spliceComments(cleanData, comments, mode, ext);
                 } else {
@@ -677,7 +763,6 @@ Options:
     rl.close();
 }
 
-// Run the CLI interface if this script is the main module [ds]
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/bin/post-commit.js

@@ -3,60 +3,61 @@ const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
 
-/** Main execution block [ds] */
+/** Main execution block for post-commit hook [ds] */
 try {
-    // Allow users to completely bypass the AI hook using an environment variable [ds]
+    // Check if SKIP_DEVSPLAIN environment variable is set [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]
+    // Determine if Git is in a rebasing, merging, or cherry-picking state [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'));
 
+    // Exit if Git is in a rebasing, merging, or cherry-picking state to avoid history conflicts [ds]
     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] */
+    // Retrieve the last commit message [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 last commit message [ds]
+    // Get a list of changed files in the last commit [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/);
 
-    /** List of valid file extensions for commenting [ds] */
+    /** List of valid file extensions for auto-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'
     ];
 
-    /** Filter files to be commented [ds] */
+    /** Filter function to determine which files to auto-comment [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 found for auto-commenting [ds]
     console.log(`[devsplain] Found ${filesToComment.length} file(s) in the last commit to auto-comment.`);
 
-    // Parse command line arguments for mode flag [ds]
+    // Parse command-line arguments for mode flags [ds]
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
@@ -65,8 +66,9 @@ try {
     let commentedAny = false;
     const successfullyCommentedFiles = [];
 
-    /** Iterate over files to comment [ds] */
+    /** Loop through each file to auto-comment [ds] */
     for (const file of filesToComment) {
+        // Attempt to read file contents and previous version [ds]
         try {
             const ext = path.extname(file).toLowerCase();
             const contentHead = fs.readFileSync(file, 'utf8');
@@ -79,11 +81,12 @@ try {
             } catch (prevErr) {
             }
 
-            // Compare file content before and after the last commit [ds]
+            // Check if file contents have changed (ignoring comments) [ds]
             if (contentPrev) {
                 const cleanHead = spliceComments(contentHead, [], 'prune', ext);
                 const cleanPrev = spliceComments(contentPrev, [], 'prune', ext);
-                if (cleanHead === cleanPrev) {
+                const isExplicitOverwrite = !!process.env.DS_OVER;
+                if (cleanHead === cleanPrev && !isExplicitOverwrite) {
                     console.log(`[devsplain] Skipping ${file}: commit contains only comment changes.`);
                     continue;
                 }
@@ -91,11 +94,16 @@ try {
         } catch (cleanErr) {
         }
 
-        // Comment the file using the CLI [ds]
+        // Log and attempt to auto-comment the current file [ds]
         console.log(`[devsplain] Automatically commenting file: ${file}`);
         try {
+            let extraFlags = '';
+            if (process.env.DS_OVER) extraFlags += ' --overwrite';
+            if (process.env.DS_KEEP) extraFlags += ' --keep';
+
+            // Construct the command to run the auto-commenting CLI [ds]
             const cliPath = path.join(__dirname, 'cli.js');
-            execSync(`node "${cliPath}" "${file}" --force${modeFlag}`, { stdio: 'inherit' });
+            execSync(`node "${cliPath}" "${file}" --force${modeFlag}${extraFlags}`, { stdio: 'inherit' });
             commentedAny = true;
             successfullyCommentedFiles.push(file);
         } catch (err) {
@@ -103,16 +111,14 @@ try {
         }
     }
 
-    /** Stage and commit auto-generated comments if any [ds] */
+    /** If any files were successfully commented, stage and commit changes [ds] */
     if (commentedAny) {
-        // 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...');
@@ -120,7 +126,7 @@ try {
             console.log('[devsplain] Comments committed successfully! Rollback via: git reset --hard HEAD~1');
         }
     }
-/** Catch and log any errors [ds] */
+// Catch and log any errors that occur during execution [ds]
 } catch (e) {
     console.warn(`[devsplain] Warning: post-commit hook script failed: ${e.message}`);
 }

package/bin/setup-hook.js

@@ -3,36 +3,44 @@ const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
 
-/** Installs Git hooks for the repository. [ds] */
+/** Installs Git hooks and configures commit settings [ds] */
 async function installHooks() {
     try {
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+        const gitRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
         const hooksDir = path.join(gitDir, 'hooks');
         if (!fs.existsSync(hooksDir)) {
             fs.mkdirSync(hooksDir, { recursive: true });
         }
 
         let modeChoice = '1';
-        // Check if process is running in a TTY to prompt for user input [ds]
+        // Check if process is run in a TTY environment [ds]
         if (process.stdout.isTTY) {
             const rl = readline.createInterface({
                 input: process.stdin,
                 output: process.stdout
             });
-            // Create a readline interface for user input [ds]
             const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
-            // Display a menu for the user to select the default commenting mode [ds]
+            // Prompt user to select the default commenting mode [ds]
             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';
+            
+            // Validate user input for commenting mode [ds]
+            while (true) {
+                const answer = (await askQuestion('Select (1-3, default: 1): ')).trim();
+                if (answer === '' || ['1', '2', '3'].includes(answer)) {
+                    modeChoice = answer || '1';
+                    break;
+                }
+                console.log('Invalid choice. Please select 1, 2, or 3.');
+            }
             rl.close();
         }
 
-        // Determine the command line arguments based on the chosen mode [ds]
+        // Determine mode arguments based on user choice [ds]
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -40,7 +48,7 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Define the path to the pre-commit hook file [ds]
+        // Define the pre-commit hook script [ds]
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
@@ -49,16 +57,16 @@ if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
   npm test || exit 1
 fi
 `;
+        // Write the pre-commit hook to the Git hooks directory [ds]
         fs.writeFileSync(preCommitHookPath, preCommitContent);
-        // Attempt to set the execute permissions for the pre-commit hook file [ds]
         try {
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Define the path to the post-commit script [ds]
+        // Define the post-commit script path [ds]
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Define the path to the post-commit hook file [ds]
+        // Define the post-commit hook script [ds]
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
@@ -66,22 +74,46 @@ echo "Auto-generating comments for files in the last commit..."
 node "${postCommitScript}"${modeArgs} || exit 1
 `;
         fs.writeFileSync(postCommitHookPath, postCommitContent);
-        // Attempt to set the execute permissions for the post-commit hook file [ds]
         try {
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Display a success message if the hooks are installed successfully [ds]
-        console.log('Success: Native Git pre-commit and post-commit hooks installed successfully!');
-    // Catch and handle any exceptions that occur during the installation process [ds]
+        // Inform the user about the successful installation of the post-commit hook [ds]
+        console.log(`[devsplain] Git post-commit hook successfully installed at: ${postCommitHookPath}`);
+
+        // Check if a .devsplainignore file exists in the Git root directory [ds]
+        const ignorePath = path.join(gitRoot, '.devsplainignore');
+        if (!fs.existsSync(ignorePath)) {
+            const defaultIgnore = `node_modules/
+.git/
+dist/
+build/
+out/
+.next/
+.nuxt/
+.svelte-kit/
+venv/
+env/
+.venv/
+.vscode/
+.idea/
+coverage/
+tests/
+__tests__/
+fixtures/
+`;
+            fs.writeFileSync(ignorePath, defaultIgnore);
+            console.log(`[devsplain] Created default .devsplainignore file at: ${ignorePath}`);
+        }
     } catch (e) {
         console.warn('Warning: Could not set up Git hooks (not inside a git repository or git command missing).');
+        console.warn(e.message);
     }
 }
 
-// Check if this script is being run directly (not being required as a module) [ds]
+// Check if the script is run as the main module [ds]
 if (require.main === module) {
     installHooks();
 }
-// Export the installHooks function as a module [ds]
+// Export the installHooks function for external use [ds]
 module.exports = installHooks;

package/lib/config.js

@@ -4,7 +4,36 @@ const os = require('os');
 const readline = require('readline');
 const configPath = path.join(os.homedir(), '.devsplainrc');
 
-/** Retrieves the configuration for the AI provider. If a configuration file exists and no forceWizard flag is provided, the existing configuration will be returned. Otherwise, the function will prompt the user to input their configuration details. [ds] */
+/** Prompts the user for a secret input, hiding the input from the console [ds] */
+function askSecret(query) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    process.stdout.write(query);
+    process.stdin.setRawMode(true);
+    let key = '';
+    const onData = (char) => {
+      char = char.toString();
+      if (char === '\n' || char === '\r') {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener('data', onData);
+        process.stdout.write('\n');
+        rl.close();
+        resolve(key);
+      } else if (char === '\u0003') { // Ctrl+C
+        process.exit();
+      } else {
+        key += char;
+        process.stdout.write('*');
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+/** Retrieves the configuration, either from environment variables or by prompting the user [ds] */
 async function getConfig(forceWizard = false) {
   if (process.env.DEVSPLAIN_API_KEY || process.env.DEVSPLAIN_PROVIDER) {
     const provider = process.env.DEVSPLAIN_PROVIDER || 'gemini';
@@ -18,24 +47,24 @@ async function getConfig(forceWizard = false) {
     };
   }
 
-  // Check if configuration file exists or if forceWizard flag is set [ds]
+  // If the configuration file does not exist or forceWizard is true, prompt the user to configure [ds]
   if (!fs.existsSync(configPath) || forceWizard) {
-    const rl = readline.createInterface({
+    let rl = readline.createInterface({
       input: process.stdin,
       output: process.stdout
     });
-    const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+    let askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
     let config = null;
     let confirmed = false;
 
-    // Continuously prompt user for configuration details until confirmation [ds]
+    // Continuously prompt the user until the configuration is confirmed [ds]
     while (!confirmed) {
       let baseUrl = "";
       let model = "";
       let provider = "";
 
-      // Display available AI provider options [ds]
+      // Display the list of available AI providers [ds]
       console.log("\nWhich AI Provider Do You want to use?");
       console.log("1. Groq (Free, Fast, Llama-3)");
       console.log("2. Gemini (Free Tier)");
@@ -43,10 +72,8 @@ async function getConfig(forceWizard = false) {
       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-5): ");
 
-      // Handle selected AI provider option [ds]
       if (choice === '1') {
         provider = 'groq';
         baseUrl = 'https://api.groq.com/openai';
@@ -67,8 +94,16 @@ async function getConfig(forceWizard = false) {
         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): ");
+        while (true) {
+          model = (await askQuestion("Model name (e.g., llama3): ")).trim();
+          if (model) break;
+          console.log("Model name cannot be empty.");
+        }
+        while (true) {
+          baseUrl = (await askQuestion("Base URL (e.g., http://localhost:11434): ")).trim();
+          if (baseUrl) break;
+          console.log("Base URL cannot be empty.");
+        }
       } else if (choice === '5') {
         provider = 'claude';
         baseUrl = 'https://api.anthropic.com';
@@ -80,38 +115,82 @@ async function getConfig(forceWizard = false) {
         continue;
       }
 
-      // Get API key from user [ds]
-      const apiKey = await askQuestion("Paste your API key (leave blank for local models): ");
+      // Prompt the user for an API key [ds]
+      let apiKey = '';
+      while (true) {
+        const promptMsg = provider === 'custom' 
+          ? "Paste your API key (leave blank for local models): " 
+          : "Paste your API key: ";
+
+        if (process.stdin.isTTY) {
+          rl.close();
+          apiKey = await askSecret(promptMsg);
+
+          rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+          });
+          askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+        } else {
+          apiKey = await askQuestion(promptMsg);
+        }
+
+        apiKey = apiKey.trim();
+        if (provider === 'custom' || apiKey) {
+          break;
+        }
+        console.log(`API key is required for provider '${provider}'.`);
+      }
+
+      // Ask the user if they want to enable auto-pruning of existing comments [ds]
+      let autoPrune = false;
+      while (true) {
+        const pruneAns = (await askQuestion("Do you want devsplain to aggressively prune (overwrite) existing human/AI comments? (y/n, default: n): ")).trim().toLowerCase();
+        if (pruneAns === '' || pruneAns === 'n' || pruneAns === 'no') {
+          autoPrune = false;
+          break;
+        } else if (pruneAns === 'y' || pruneAns === 'yes') {
+          autoPrune = true;
+          break;
+        }
+        console.log("Invalid choice. Please enter 'y' or 'n'.");
+      }
 
-      // Display configuration summary [ds]
+      // Display a summary of the configuration [ds]
       console.log("\n--- Configuration Summary ---");
-      console.log(`Provider: ${provider}`);
-      console.log(`Model:    ${model}`);
-      console.log(`Base URL: ${baseUrl || 'N/A'}`);
-      console.log(`API Key:  ${apiKey ? apiKey.substring(0, 4) + '*'.repeat(Math.max(0, apiKey.length - 4)) : 'None'}`);
+      console.log(`Provider:     ${provider}`);
+      console.log(`Model:        ${model}`);
+      console.log(`Base URL:     ${baseUrl || 'N/A'}`);
+      console.log(`API Key:      ${apiKey ? apiKey.substring(0, 4) + '*'.repeat(Math.max(0, apiKey.length - 4)) : 'None'}`);
+      console.log(`Auto-Prune:   ${autoPrune ? 'Yes' : 'No'}`);
       console.log("-----------------------------\n");
 
-      // Confirm configuration with user [ds]
-      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.");
+      // Confirm the configuration with the user [ds]
+      while (true) {
+        const confirm = (await askQuestion("Does this look correct? (y/n, default: y): ")).trim().toLowerCase();
+        if (confirm === '' || confirm === 'y' || confirm === 'yes') {
+          config = {
+            provider,
+            apiKey,
+            model,
+            baseUrl,
+            autoPrune
+          };
+          confirmed = true;
+          break;
+        } else if (confirm === 'n' || confirm === 'no') {
+          break;
+        }
+        console.log("Invalid choice. Please enter 'y' or 'n'.");
       }
     }
 
     rl.close();
 
-    // Write configuration to file [ds]
+    // Write the configuration to the config file [ds]
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
     try {
-      // Set file permissions to prevent unauthorized access [ds]
+      // Set the permissions of the config file to prevent other users from reading it [ds]
       if (process.platform !== 'win32') {
         fs.chmodSync(configPath, 0o600);
       }
@@ -120,11 +199,9 @@ async function getConfig(forceWizard = false) {
 
     return config;
   } else {
-    // Read existing configuration from file [ds]
     const rawData = fs.readFileSync(configPath, 'utf8');
     return JSON.parse(rawData);
   }
 }
 
-// Export the getConfig function [ds]
-module.exports = { getConfig };
+module.exports = { getConfig };

package/package.json

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