devsplain 1.5.4 → 1.5.6

package/bin/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 
 const { getComments } = require('../lib/llm.js');
 const { getConfig } = require('../lib/config.js');
@@ -9,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();
@@ -22,7 +23,7 @@ function isGitDirty() {
     return false;
 }
 
-/** Determines if a specific line index falls within a string literal */
+/** 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;
@@ -31,7 +32,6 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     let inSingle = false;
     let inDouble = false;
 
-    // Iterate through lines prior to the target to track string/block state
     for (let i = 0; i < targetLineIndex; i++) {
         const line = lines[i];
         let j = 0;
@@ -52,7 +52,6 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
                     }
                 }
             } else {
-                // Check for unescaped backtick (JS template strings) or quotes
                 if (!inSingle && !inDouble && line[j] === '`') {
                     let escaped = false;
                     let k = j - 1;
@@ -98,7 +97,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
 }
 
-/** Performs a lexical analysis to categorize code lines and comment blocks */
+/** 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());
@@ -110,7 +109,6 @@ function analyzeComments(lines, ext = '') {
     let inDouble = false;
     let inBlockJS = false;
     let inBlockHTML = false;
-    // Iterate through each line character by character to detect comment boundaries
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         let commentStartIndex = -1;
@@ -250,9 +248,8 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splices generated comments into the source data or removes existing ones */
+/** Splices comments into code or cleans existing ones, with safety checks. */
 function spliceComments(data, comments, mode = 'default', ext = '') {
-    // Determine platform-specific line endings
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
     const originalLines = data.split(/\r?\n/);
@@ -262,12 +259,14 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     const annotated = originalLines.map((text, index) => ({ text, originalIndex: index }));
     let analysis = null;
 
-    // 'clean' mode removes all existing comments/documentation
     if (mode === 'clean') {
         analysis = analyzeComments(originalLines, ext);
         const finalDeletions = new Set();
         for (let i = 0; i < originalLines.length; i++) {
             const lineNum = i + 1;
+            if (originalLines[i].trim().startsWith('#!')) {
+                continue;
+            }
             if (analysis[i].isPureComment) {
                 finalDeletions.add(lineNum);
             } else if (analysis[i].commentStartIndex !== -1) {
@@ -290,6 +289,10 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             const trimmedLine = targetLine.trim();
 
             const lineAnalysis = analysis[lineNum - 1];
+            if (trimmedLine.startsWith('#!')) {
+                continue;
+            }
+
             const isCommentLine = 
                 lineAnalysis.isInsideBlock ||
                 lineAnalysis.isPureComment ||
@@ -311,7 +314,6 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             annotated.splice(lineNum - 1, 1);
         }
     } else {
-        // 'default'/'light'/'full' mode: Inject AI-generated comments
         for (const c of validComments) {
             if (isLineInsideString(originalLines, c.line - 1, ext)) {
                 console.warn(`[devsplain] Skipping comment insertion at line ${c.line} to avoid string literal corruption.`);
@@ -374,7 +376,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Main entry point for the CLI tool logic */
+/** 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));
@@ -491,7 +493,7 @@ Options:
     let successCount = 0;
     let failCount = 0;
 
-    /** Recursively traverses the file system to identify and process source files */
+    /** Recursively processes files or directories to apply AI-generated comments. */
     async function processPath(targetPath) {
         const stats = fs.statSync(targetPath);
 
@@ -536,7 +538,6 @@ Options:
 
             console.log(` Analyzing ${filename} in ${mode} mode...`);
             try {
-                // Logic to either clean existing comments or replace/insert new ones
                 let comments = [];
                 let commentedCode;
                 if (mode !== 'clean') {
@@ -552,7 +553,6 @@ Options:
                     console.log(`---------------------------------------\n`);
                     const answer = await askQuestion("Type 'write' to save to file, or press any key to discard: ");
                     if (answer.toLowerCase() === 'write') {
-                        // Use temporary file for atomic write operations
                         const tempPath = targetPath + '.tmp';
                         fs.writeFileSync(tempPath, commentedCode, 'utf8');
                         fs.renameSync(tempPath, targetPath);
@@ -590,6 +590,7 @@ Options:
     rl.close();
 }
 
+// Check if the script is run directly vs required as a module
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/package.json

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