devsplain 1.5.5 → 1.6.0

package/README.md

@@ -8,7 +8,8 @@ An industrial-grade, agent-agnostic CLI tool that automatically adds JSDoc and i
 
 - **Mathematical Safety Invariants**: Uses an index-preserving splicing engine. Your functional code is mathematically verified to remain identical before and after commenting.
 - **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.
-- **Local Deterministic Scrubber**: The `--clean` flag strips comments locally using a deterministic lexical state machine—no LLM calls, API keys, or internet required.
+- **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).
 - **Exponential Backoff**: Resilient AI request handler that automatically retries rate-limited requests with exponential backoff.
@@ -78,7 +79,8 @@ devsplain <file-or-directory> [options]
 | `--full` | Aggressive commenting. Explains complex logic blocks line-by-line inside functions. |
 | `--dry-run` | Preview comments in the terminal without writing to files. Prompts for manual save confirmation. |
 | `--force` | Bypasses the safety block check that prevents running `devsplain` on a dirty Git working tree. |
-| `--clean` | Scrubber mode. Deterministically removes all comments and docstrings from source files. |
+| `--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). |
 | `--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. |
@@ -97,9 +99,12 @@ devsplain src/index.js --light
 # Deep logic commenting on a folder (skips node_modules, .git, etc.)
 devsplain src/ --full
 
-# Clean and scrub comments from your codebase locally without AI calls
+# Clean and scrub AI-generated comments locally without API calls
 devsplain lib/ --clean
 
+# Destructively remove ALL comments (both AI and manual) from a folder
+devsplain lib/ --prune
+
 # Headless run using overriding credentials
 devsplain src/utils.ts --provider gemini --model gemini-2.0-flash --api-key YOUR_KEY
 ```

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 */
+/** Checks if the current Git repository is dirty by inspecting status. */
 function isGitDirty() {
     try {
         const gitDir = execSync('git rev-parse --is-inside-work-tree', { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim();
@@ -23,7 +23,8 @@ function isGitDirty() {
     return false;
 }
 
-/** Determines if a line is within a string literal in the source code */
+/** Determines if a specific line index is within a string literal (handling quotes/backticks). [ds] */
+/** Determines if a specific line index is within a string literal (handling quotes/backticks). */
 function isLineInsideString(lines, targetLineIndex, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     let inBacktick = false;
@@ -97,7 +98,8 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
 }
 
-/** Analyzes source code to identify comments and code blocks */
+/** Parses a file to identify pure comments and block structures. [ds] */
+/** Parses a file to identify pure comments and block structures. */
 function analyzeComments(lines, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
@@ -248,7 +250,8 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Applies or removes comments from source data based on a specified mode */
+/** Splices comments into code or cleans existing ones, with safety checks. [ds] */
+/** Splices comments into code or cleans existing ones, with safety checks. */
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -258,19 +261,72 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
 
     const annotated = originalLines.map((text, index) => ({ text, originalIndex: index }));
     let analysis = null;
+    let dsBlocks = new Set();
 
-    if (mode === 'clean') {
+    if (mode === 'clean' || mode === 'prune') {
         analysis = analyzeComments(originalLines, ext);
         const finalDeletions = new Set();
+        
+        if (mode === 'clean') {
+            let i = 0;
+            while (i < originalLines.length) {
+                if (analysis[i].isInsideBlock) {
+                    let start = i;
+                    let end = i;
+                    while (end < originalLines.length && analysis[end].isInsideBlock) end++;
+                    
+                    let blockStart = start - 1;
+                    let blockEnd = end - 1;
+                    
+                    let hasDs = false;
+                    for (let k = blockStart; k <= blockEnd; k++) {
+                        if (originalLines[k].includes('[ds]')) hasDs = true;
+                    }
+                    
+                    if (hasDs) {
+                        for (let k = blockStart; k <= blockEnd; k++) {
+                            dsBlocks.add(k + 1);
+                        }
+                    }
+                    i = end;
+                } else {
+                    i++;
+                }
+            }
+        }
+
         for (let i = 0; i < originalLines.length; i++) {
             const lineNum = i + 1;
-            if (analysis[i].isPureComment) {
-                finalDeletions.add(lineNum);
-            } else if (analysis[i].commentStartIndex !== -1) {
-                annotated[i].text = originalLines[i].slice(0, analysis[i].commentStartIndex).trimEnd();
+            const lineStr = originalLines[i];
+            const lineAnalysis = analysis[i];
+
+            if (lineStr.trim().startsWith('#!')) {
+                continue;
+            }
+
+            if (mode === 'prune') {
+                if (lineAnalysis.isPureComment) {
+                    finalDeletions.add(lineNum);
+                } else if (lineAnalysis.commentStartIndex !== -1) {
+                    annotated[i].text = lineStr.slice(0, lineAnalysis.commentStartIndex).trimEnd();
+                }
+            } else if (mode === 'clean') {
+                const isDsBlockLine = dsBlocks.has(lineNum);
+                const hasDsInline = lineStr.includes('[ds]');
+
+                if (lineAnalysis.isPureComment) {
+                    if (isDsBlockLine || hasDsInline) {
+                        finalDeletions.add(lineNum);
+                    }
+                } else if (lineAnalysis.commentStartIndex !== -1) {
+                    if (isDsBlockLine || hasDsInline) {
+                        annotated[i].text = lineStr.slice(0, lineAnalysis.commentStartIndex).trimEnd();
+                    }
+                }
             }
         }
 
+
         for (const c of validComments) {
             const lineIdx = c.line - 1;
             if (lineIdx >= 0 && lineIdx < originalLines.length) {
@@ -321,9 +377,23 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             const indentMatch = targetLine.match(/^([ \t]*)/);
             const indentation = indentMatch ? indentMatch[1] : '';
 
-            const commentLines = c.comment.split(/\r?\n/).map(line => {
-                const trimmed = line.trimStart();
+            const commentLines = c.comment.split(/\r?\n/).map((line, idx) => {
+                let trimmed = line.trimStart();
                 if (!trimmed) return '';
+
+                const isSingleLine = trimmed.startsWith('//') || trimmed.startsWith('#') || trimmed.startsWith('--');
+                const isBlockEnd = trimmed.endsWith('*/') || trimmed.endsWith('-->');
+
+                if (isSingleLine) {
+                    trimmed = trimmed + ' [ds]';
+                } else if (idx === 0) {
+                    if (isBlockEnd) {
+                        trimmed = trimmed.replace(/(\*\/|-->)$/, '[ds] $1');
+                    } else {
+                        trimmed = trimmed + ' [ds]';
+                    }
+                }
+
                 if (trimmed.startsWith('*') && !trimmed.startsWith('*/') && !trimmed.startsWith('/*')) {
                     return indentation + ' ' + trimmed;
                 }
@@ -345,12 +415,17 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
         if (text === originalLine) {
             return true;
         }
-        if (mode === 'clean' && analysis) {
+        if ((mode === 'clean' || mode === 'prune') && analysis) {
             const lineAnalysis = analysis[origIdx];
             if (lineAnalysis && lineAnalysis.commentStartIndex !== -1 && !lineAnalysis.isPureComment) {
-                const expectedStripped = originalLine.slice(0, lineAnalysis.commentStartIndex).trimEnd();
-                if (text === expectedStripped) {
-                    return true;
+                const isDsBlockLine = dsBlocks.has(origIdx + 1);
+                const hasDsInline = originalLine.includes('[ds]');
+                
+                if (mode === 'prune' || (mode === 'clean' && (hasDsInline || isDsBlockLine))) {
+                    const expectedStripped = originalLine.slice(0, lineAnalysis.commentStartIndex).trimEnd();
+                    if (text === expectedStripped) {
+                        return true;
+                    }
                 }
             }
         }
@@ -373,7 +448,8 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Main CLI execution logic */
+/** Main entry point for the CLI tool. [ds] */
+/** Main entry point for the CLI tool. */
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -392,6 +468,8 @@ Options:
   --full              Add detailed JSDoc/block comments and inline comments
   --dry-run           Preview comments without writing to file
   --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)
   --model <name>      Override AI model name
   --api-key <key>     Override API key for the provider
@@ -426,7 +504,7 @@ Options:
         return;
     }
 
-    // Helper to retrieve specific CLI argument values
+    // Helper to extract flag values from command line arguments [ds]
     const getArgValue = (flag) => {
         const index = args.indexOf(flag);
         if (index !== -1 && index + 1 < args.length) {
@@ -459,6 +537,7 @@ Options:
     if (args.includes('--light')) mode = 'light';
     if (args.includes('--full')) mode = 'full';
     if (args.includes('--clean')) mode = 'clean';
+    if (args.includes('--prune')) mode = 'prune';
     const isDryRun = args.includes('--dry-run');
     const isForce = args.includes('--force');
 
@@ -491,7 +570,8 @@ Options:
     let successCount = 0;
     let failCount = 0;
 
-    /** Recursively processes files or directories to apply comments */
+    /** Recursively processes files or directories to apply AI-generated comments. [ds] */
+    /** Recursively processes files or directories to apply AI-generated comments. */
     async function processPath(targetPath) {
         const stats = fs.statSync(targetPath);
 
@@ -504,7 +584,6 @@ Options:
                 '.vscode', '.idea', 'coverage'   
             ];
 
-            // Skip common dependency and configuration folders
             if (ignoredFolders.includes(folderName)) {
                 return;
             }
@@ -539,7 +618,6 @@ Options:
             try {
                 let comments = [];
                 let commentedCode;
-                // Perform comment processing: Clean existing, then inject new comments via LLM
                 if (mode !== 'clean') {
                     const cleanData = spliceComments(data, [], 'clean', ext);
                     comments = await getComments(cleanData, filename, config, mode);
@@ -590,7 +668,8 @@ Options:
     rl.close();
 }
 
-// Initialize the CLI application if executed as a script
+// Check if the script is run directly vs required as a module [ds]
+// Check if the script is run directly vs required as a module
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/bin/post-commit.js

@@ -3,14 +3,17 @@ const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
 
+/** Main execution block to detect changes and process documentation generation [ds] */
 /** Main execution block to detect changes and process documentation generation */
 try {
     // Prevent recursive loops if the previous commit was an automated documentation commit
+    // Retrieve the last commit message to prevent infinite loops during automated commits [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 file paths modified in the current commit [ds]
     const changedFilesStr = execSync('git diff-tree --no-commit-id --name-only -r HEAD', { encoding: 'utf8' }).trim();
     if (!changedFilesStr) {
         process.exit(0);
@@ -18,6 +21,7 @@ try {
     // Retrieve list of files modified in the latest commit
     const changedFiles = changedFilesStr.split(/\r?\n/);
 
+    // Define allowed file types for documentation processing [ds]
     const validExtensions = [
         '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
         '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs',
@@ -37,6 +41,7 @@ try {
     console.log(`[devsplain] Found ${filesToComment.length} file(s) in the last commit to auto-comment.`);
 
     // Parse command line arguments to determine documentation verbosity mode
+    // Parse CLI arguments for verbosity preferences [ds]
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
@@ -51,6 +56,7 @@ try {
             const contentHead = fs.readFileSync(file, 'utf8');
             let contentPrev = '';
             try {
+                // Attempt to retrieve the file version from the previous commit for change comparison [ds]
                 // Attempt to fetch the file content from the previous commit state for comparison
                 contentPrev = execSync(`git show HEAD~1:"${file}"`, { 
                     encoding: 'utf8', 
@@ -60,9 +66,10 @@ try {
             }
 
             if (contentPrev) {
+                // Prune comments to isolate actual code changes and ignore documentation-only commits [ds]
                 // Strip comments from head and previous versions to detect if logic actually changed
-                const cleanHead = spliceComments(contentHead, [], 'clean', ext);
-                const cleanPrev = spliceComments(contentPrev, [], 'clean', ext);
+                const cleanHead = spliceComments(contentHead, [], 'prune', ext);
+                const cleanPrev = spliceComments(contentPrev, [], 'prune', ext);
                 // Skip processing if only comments were modified in the commit
                 if (cleanHead === cleanPrev) {
                     console.log(`[devsplain] Skipping ${file}: commit contains only comment changes.`);
@@ -75,6 +82,7 @@ try {
         console.log(`[devsplain] Automatically commenting file: ${file}`);
         try {
             // Execute the CLI generator for the specific file
+            // Path to the underlying documentation generation engine [ds]
             const cliPath = path.join(__dirname, 'cli.js');
             execSync(`node "${cliPath}" "${file}" --force${modeFlag}`, { stdio: 'inherit' });
             commentedAny = true;
@@ -83,6 +91,7 @@ try {
         }
     }
 
+    // Stage changes back to the repo if new documentation was generated [ds]
     // If changes were made by the generator, stage and commit the result back to the repository
     if (commentedAny) {
         const status = execSync('git diff --name-only', { encoding: 'utf8' }).trim();

package/bin/setup-hook.js

@@ -5,25 +5,25 @@ const readline = require('readline');
 
 /**
  * Orchestrates the installation of Git pre-commit and post-commit hooks.
- * Detects the local .git directory and configures hooks with user-specified mode.
+ * Sets up necessary directories and writes hook files with user-selected configuration.
 */
 async function installHooks() {
     try {
-        // Determine the path to the .git directory
+        // Determine the actual git directory path using git command line tool
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
         const hooksDir = path.join(gitDir, 'hooks');
+        // Ensure the hooks directory exists before attempting to write files
         if (!fs.existsSync(hooksDir)) {
             fs.mkdirSync(hooksDir, { recursive: true });
         }
 
         let modeChoice = '1';
-        // Interact with user via terminal to select documentation verbosity
+        // Prompt the user for mode selection only if running in an interactive terminal session
         if (process.stdout.isTTY) {
             const rl = readline.createInterface({
                 input: process.stdin,
                 output: process.stdout
             });
-            // Promisify readline to allow async flow control
             const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
             console.log('\nSelect default commenting mode for Git commits:');
@@ -35,7 +35,7 @@ async function installHooks() {
             rl.close();
         }
 
-        // Map selected mode to command-line arguments for the post-commit script
+        // Map user input to CLI arguments for the post-commit script execution
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -43,23 +43,25 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Create the executable pre-commit script
+        // Generate and write the pre-commit shell script to trigger tests before committing
         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
+if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
+  echo "Running pre-commit tests..."
+  npm test || exit 1
+fi
 `;
         fs.writeFileSync(preCommitHookPath, preCommitContent);
         try {
-            // Ensure the hook file is executable
+            // Apply execute permissions to the hook file
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Locate the source script for post-commit actions
+        // Normalize the path for cross-platform compatibility when injecting into shell script
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Create the executable post-commit script that calls the documentation engine
+        // Generate and write the post-commit shell script to execute the documentation generation
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
@@ -67,8 +69,8 @@ echo "Auto-generating comments for files in the last commit..."
 node "${postCommitScript}"${modeArgs} || exit 1
 `;
         fs.writeFileSync(postCommitHookPath, postCommitContent);
+        // Apply execute permissions to the hook file
         try {
-            // Ensure the hook file is executable
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
@@ -78,6 +80,7 @@ node "${postCommitScript}"${modeArgs} || exit 1
     }
 }
 
+// Execute installation automatically if this script is run as the entry point
 if (require.main === module) {
     installHooks();
 }

package/package.json

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