devsplain 1.5.1 → 1.5.2

package/bin/cli.js

@@ -22,7 +22,7 @@ function isGitDirty() {
     return false;
 }
 
-/** Determines if a specific line index is inside a string or multiline literal */
+/** Determines if a specific line index falls within a multi-line string or block */
 function isLineInsideString(lines, targetLineIndex, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     let inBacktick = false;
@@ -96,7 +96,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
 }
 
-/** Analyzes code to identify pure comment lines and block boundaries */
+/** Analyzes code to determine which lines are purely comments */
 function analyzeComments(lines, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
@@ -247,7 +247,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splicers or removes comments from source data based on the requested mode */
+/** Splices AI-generated comments into source code or cleans existing ones */
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -255,9 +255,11 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     const sortedComments = [...comments].sort((a, b) => b.line - a.line);
     const validComments = sortedComments.filter(c => c.line >= 1 && c.line <= originalLines.length + 1);
 
+    // Map lines to objects to track original positioning after splicing
     const annotated = originalLines.map((text, index) => ({ text, originalIndex: index }));
     let analysis = null;
 
+    // Logic for removing existing comments
     if (mode === 'clean') {
         analysis = analyzeComments(originalLines, ext);
         const finalDeletions = new Set();
@@ -279,6 +281,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
 
         const linesToDelete = Array.from(finalDeletions).sort((a, b) => b - a);
 
+        // Process deletions in reverse to maintain line integrity
         for (const lineNum of linesToDelete) {
             const targetLine = originalLines[lineNum - 1];
             if (!targetLine) continue;
@@ -313,6 +316,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
             }
 
             const targetLine = originalLines[c.line - 1] || '';
+            // Determine indentation level for new comment blocks
             const indentMatch = targetLine.match(/^([ \t]*)/);
             const indentation = indentMatch ? indentMatch[1] : '';
 
@@ -330,6 +334,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
         }
     }
 
+    // Verify that the result matches expected output before committing to disk
     const filtered = annotated.filter(line => line.originalIndex !== -1);
     const filteredText = filtered.map(line => line.text);
     const filteredIndices = filtered.map(line => line.originalIndex);
@@ -368,7 +373,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Main CLI entry point handler */
+/** Main CLI execution loop */
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -416,7 +421,8 @@ Options:
 
     if (args.includes('--setup-hook')) {
         rl.close();
-        require('./setup-hook.js');
+        const installHooks = require('./setup-hook.js');
+        await installHooks();
         return;
     }
 
@@ -484,7 +490,7 @@ Options:
     let successCount = 0;
     let failCount = 0;
 
-    /** Recursively traverses directories to process files */
+    /** Recursively process files or directories */
     async function processPath(targetPath) {
         const stats = fs.statSync(targetPath);
 
@@ -528,6 +534,7 @@ Options:
             }
 
             console.log(` Analyzing ${filename} in ${mode} mode...`);
+            // Perform comment generation if not in 'clean' mode
             try {
                 let comments = [];
                 let commentedCode;
@@ -544,6 +551,7 @@ Options:
                     console.log(`---------------------------------------\n`);
                     const answer = await askQuestion("Type 'write' to save to file, or press any key to discard: ");
                     if (answer.toLowerCase() === 'write') {
+                        // Atomic write: write to temp file then rename
                         const tempPath = targetPath + '.tmp';
                         fs.writeFileSync(tempPath, commentedCode, 'utf8');
                         fs.renameSync(tempPath, targetPath);
@@ -581,7 +589,7 @@ Options:
     rl.close();
 }
 
-// If running as a standalone script, start the CLI; otherwise export helpers
+// Execute main if run directly, otherwise export utility functions
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/bin/setup-hook.js

@@ -4,12 +4,12 @@ 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.
+ * Initializes and installs Git pre-commit and post-commit hooks.
+ * Prompts the user for documentation mode configuration.
 */
 async function installHooks() {
     try {
-        // Resolve the actual .git directory path
+        // Resolve the root .git directory path
         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';
-        // Check if running in an interactive terminal to prompt for preferences
+        // Interactive mode requires a TTY terminal
         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
+            // Promisify the readline interface for async/await flow
             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 user selection to CLI argument flags for the post-commit handler
+        // Determine documentation style flags based on user input
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -43,7 +43,7 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Define and write the pre-commit shell script
+        // Write the pre-commit script to the git hooks directory
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
@@ -51,12 +51,12 @@ echo "Running pre-commit tests..."
 npm test || exit 1
 `;
         fs.writeFileSync(preCommitHookPath, preCommitContent);
-        // Ensure the shell script is executable by the system
         try {
+            // Ensure the hook file is executable
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Define and write the post-commit shell script
+        // Write the post-commit script that triggers documentation generation
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
@@ -64,7 +64,6 @@ 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) {}
@@ -75,5 +74,8 @@ node bin/post-commit.js${modeArgs} || exit 1
     }
 }
 
-// Execute the hook installation sequence
-installHooks();
+// Execute the function automatically if the file is run directly
+if (require.main === module) {
+    installHooks();
+}
+module.exports = installHooks;

package/package.json

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