devsplain 1.5.3 → 1.5.5

package/bin/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 
 const { getComments } = require('../lib/llm.js');
 const { getConfig } = require('../lib/config.js');
@@ -22,7 +23,7 @@ function isGitDirty() {
     return false;
 }
 
-/** Determines if a specific line index falls within a string literal */
+/** Determines if a line is within a string literal in the source code */
 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 */
+/** Analyzes source code to identify comments and code blocks */
 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 */
+/** Applies or removes comments from source data based on a specified mode */
 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,7 +259,6 @@ 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();
@@ -290,6 +286,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 +311,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 +373,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 CLI execution logic */
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -427,6 +426,7 @@ Options:
         return;
     }
 
+    // Helper to retrieve specific CLI argument values
     const getArgValue = (flag) => {
         const index = args.indexOf(flag);
         if (index !== -1 && index + 1 < args.length) {
@@ -491,7 +491,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 comments */
     async function processPath(targetPath) {
         const stats = fs.statSync(targetPath);
 
@@ -504,6 +504,7 @@ Options:
                 '.vscode', '.idea', 'coverage'   
             ];
 
+            // Skip common dependency and configuration folders
             if (ignoredFolders.includes(folderName)) {
                 return;
             }
@@ -536,9 +537,9 @@ Options:
 
             console.log(` Analyzing ${filename} in ${mode} mode...`);
             try {
-                // Logic to either clean existing comments or replace/insert new ones
                 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);
@@ -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();
 }
 
+// Initialize the CLI application if executed as a script
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/bin/post-commit.js

@@ -3,10 +3,10 @@ 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
+/** Main execution block to detect changes and process documentation generation */
 try {
+    // Prevent recursive loops if the previous commit was an automated documentation commit
     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);
     }
@@ -15,16 +15,16 @@ try {
     if (!changedFilesStr) {
         process.exit(0);
     }
+    // Retrieve list of files modified in the latest commit
     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
+    // Filter for supported file extensions and ensure the file still exists
     const filesToComment = changedFiles.filter(file => {
         const ext = path.extname(file).toLowerCase();
         return validExtensions.includes(ext) && fs.existsSync(file);
@@ -36,6 +36,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
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
@@ -43,15 +44,14 @@ try {
 
     let commentedAny = false;
 
-    // Iterate through each changed file to check if content actually changed
+    // Process each valid file to determine if documentation needs updating
     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 {
+                // Attempt to fetch the file content from the previous commit state for comparison
                 contentPrev = execSync(`git show HEAD~1:"${file}"`, { 
                     encoding: 'utf8', 
                     stdio: ['ignore', 'pipe', 'ignore'] 
@@ -60,9 +60,10 @@ try {
             }
 
             if (contentPrev) {
-                // Strip existing comments to determine if the logic changed or just documentation
+                // 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);
+                // Skip processing if only comments were modified in the commit
                 if (cleanHead === cleanPrev) {
                     console.log(`[devsplain] Skipping ${file}: commit contains only comment changes.`);
                     continue;
@@ -73,20 +74,20 @@ try {
 
         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' });
+            // Execute the CLI generator for the specific file
+            const cliPath = path.join(__dirname, 'cli.js');
+            execSync(`node "${cliPath}" "${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 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();
         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');
         }

package/bin/setup-hook.js

@@ -4,12 +4,12 @@ const { execSync } = require('child_process');
 const readline = require('readline');
 
 /**
- * Initializes and installs Git pre-commit and post-commit hooks.
- * Prompts the user for documentation mode configuration.
+ * Orchestrates the installation of Git pre-commit and post-commit hooks.
+ * Detects the local .git directory and configures hooks with user-specified mode.
 */
 async function installHooks() {
     try {
-        // Resolve the root .git directory path
+        // Determine the path to the .git directory
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
         const hooksDir = path.join(gitDir, 'hooks');
         if (!fs.existsSync(hooksDir)) {
@@ -17,13 +17,13 @@ async function installHooks() {
         }
 
         let modeChoice = '1';
-        // Interactive mode requires a TTY terminal
+        // Interact with user via terminal to select documentation verbosity
         if (process.stdout.isTTY) {
             const rl = readline.createInterface({
                 input: process.stdin,
                 output: process.stdout
             });
-            // Promisify the readline interface for async/await flow
+            // 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();
         }
 
-        // Determine documentation style flags based on user input
+        // Map selected mode to command-line arguments for the post-commit script
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -43,7 +43,7 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Write the pre-commit script to the git hooks directory
+        // Create the executable pre-commit script
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
@@ -56,15 +56,19 @@ npm test || exit 1
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Write the post-commit script that triggers documentation generation
+        // Locate the source script for post-commit actions
+        const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
+
+        // Create the executable post-commit script that calls the documentation engine
         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
+node "${postCommitScript}"${modeArgs} || exit 1
 `;
         fs.writeFileSync(postCommitHookPath, postCommitContent);
         try {
+            // Ensure the hook file is executable
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
@@ -74,7 +78,6 @@ node bin/post-commit.js${modeArgs} || exit 1
     }
 }
 
-// Execute the function automatically if the file is run directly
 if (require.main === module) {
     installHooks();
 }

package/package.json

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