devsplain 2.2.2 → 2.2.4

package/bin/cli.js

@@ -231,6 +231,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
         if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
+            inRegex = false;
         }
     }
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble || inCppRawString || inRegex;
@@ -455,6 +456,7 @@ function analyzeComments(lines, ext = '') {
         if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
+            inRegex = false;
         }
         const isEntirelyInsideBlock = isInsideBlockStart && (inBlockJS || inBlockHTML || (commentStartIndex === -1));
         let isPureComment = false;
@@ -663,6 +665,33 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     const filteredText = filtered.map(line => line.text);
     const filteredIndices = filtered.map(line => line.originalIndex);
 
+    // Validate that all inserted lines (originalIndex === -1) are valid comments or empty lines [ds]
+    const insertedLines = annotated.filter(line => line.originalIndex === -1);
+    let inInsertedBlock = false;
+    for (const item of insertedLines) {
+        const trimmed = item.text.trim();
+        if (!trimmed) continue;
+        if (inInsertedBlock) {
+            if (trimmed.includes('*/') || trimmed.includes('-->')) {
+                inInsertedBlock = false;
+            }
+            continue;
+        }
+        const isValidComment = 
+            trimmed.startsWith('//') || 
+            trimmed.startsWith('/*') || 
+            trimmed.startsWith('*') || 
+            trimmed.startsWith('#') || 
+            trimmed.startsWith('<!--') || 
+            trimmed.startsWith('--');
+        if (!isValidComment) {
+            throw new Error(`Safety Assertion Failed: Refused to insert non-comment code: "${trimmed}"`);
+        }
+        if ((trimmed.startsWith('/*') && !trimmed.includes('*/')) || (trimmed.startsWith('<!--') && !trimmed.includes('-->'))) {
+            inInsertedBlock = true;
+        }
+    }
+
     const textEqual = filteredText.every((text, idx) => {
         const origIdx = filteredIndices[idx];
         const originalLine = originalLines[origIdx];
@@ -710,8 +739,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     }
 
     if (!textEqual || !indicesSequential) {
-        console.error("\nSafety Assertion Failed: Spliced code does not match original code minus comments!");
-        process.exit(1);
+        throw new Error("Safety Assertion Failed: Spliced code does not match original code minus comments!");
     }
 
     return annotated.map(line => line.text).join(lineEnding);
@@ -818,7 +846,7 @@ Options:
     const hasOverwriteFlag = args.includes('--overwrite');
     const hasKeepFlag = args.includes('--keep');
 
-    if (process.env.NODE_ENV !== 'test' && isGitDirty() && !isForce) {
+    if (process.env.NODE_ENV !== 'test' && isGitDirty() && !isForce && !isDryRun) {
         console.error("Error: Git working tree is dirty. Please commit or stash your changes, or use --force to bypass this check.");
         rl.close();
         process.exit(1);
@@ -871,9 +899,10 @@ Options:
 
     function isPathIgnored(targetPath) {
         const filename = path.basename(targetPath);
+        const relPath = path.relative(process.cwd(), targetPath).replace(/\\/g, '/');
         for (const pattern of allIgnored) {
             const cleanPattern = pattern.replace(/\/$/, '').replace(/\\$/, '');
-            if (filename === cleanPattern) return true;
+            if (filename === cleanPattern || relPath === cleanPattern || relPath.startsWith(cleanPattern + '/')) return true;
             if (pattern.startsWith('*') && filename.endsWith(pattern.slice(1))) return true;
         }
         return false;
@@ -899,7 +928,7 @@ Options:
             const validExtensions = [
                 '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
                 '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs', 
-                '.swift', '.kt', '.dart', '.sh'
+                '.swift', '.kt', '.dart', '.sh', '.sql'
             ];
 
             if (!validExtensions.includes(ext)) {

package/bin/post-commit.js

@@ -1,49 +1,41 @@
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
 
-/** Main execution block for post-commit hook [ds] */
 try {
-    // 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);
     }
 
-    // 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);
     }
 
-    // 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 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();
+    const changedFilesStr = execSync('git diff-tree --no-commit-id --name-only -r --root HEAD', { encoding: 'utf8' }).trim();
     if (!changedFilesStr) {
         process.exit(0);
     }
     const changedFiles = changedFilesStr.split(/\r?\n/);
 
-    /** 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'
+        '.swift', '.kt', '.dart', '.sh', '.sql'
     ];
 
-    /** 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/');
@@ -54,10 +46,8 @@ try {
         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 flags [ds]
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
@@ -66,9 +56,7 @@ try {
     let commentedAny = false;
     const successfullyCommentedFiles = [];
 
-    /** 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');
@@ -81,7 +69,6 @@ try {
             } catch (prevErr) {
             }
 
-            // Check if file contents have changed (ignoring comments) [ds]
             if (contentPrev) {
                 const cleanHead = spliceComments(contentHead, [], 'prune', ext);
                 const cleanPrev = spliceComments(contentPrev, [], 'prune', ext);
@@ -94,16 +81,15 @@ try {
         } catch (cleanErr) {
         }
 
-        // 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}${extraFlags}`, { stdio: 'inherit' });
+            const cliArgs = [cliPath, file, '--force'];
+            if (modeFlag.trim()) cliArgs.push(modeFlag.trim());
+            if (process.env.DS_OVER) cliArgs.push('--overwrite');
+            if (process.env.DS_KEEP) cliArgs.push('--keep');
+
+            execFileSync(process.execPath, cliArgs, { stdio: 'inherit' });
             commentedAny = true;
             successfullyCommentedFiles.push(file);
         } catch (err) {
@@ -111,14 +97,12 @@ try {
         }
     }
 
-    /** If any files were successfully commented, stage and commit changes [ds] */
     if (commentedAny) {
         for (const file of successfullyCommentedFiles) {
             try {
-                execSync(`git add "${file}"`);
+                execFileSync('git', ['add', file]);
             } catch (addErr) {}
         }
-        
         const stagedChanges = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim();
         if (stagedChanges.length > 0) {
             console.log('[devsplain] Staging and committing auto-generated comments...');
@@ -126,7 +110,6 @@ try {
             console.log('[devsplain] Comments committed successfully! Rollback via: git reset --hard HEAD~1');
         }
     }
-// 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,53 +3,79 @@ const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
 
-// Installs Git hooks for automatic comment generation [ds]
+/** [ds]
+ * Automatically detects the local Git repository structure, configures hook directories,
+ * allows the user to select a commenting intensity mode, installs executable pre-commit
+ * and post-commit shell hooks, and ensures a .devsplainignore file is generated or updated
+ * based on existing .gitignore patterns to defer specific paths from automated comment injection.
+*/
 async function installHooks() {
     try {
+        // Exec 'git rev-parse --git-dir' to identify the absolute path to the Git directory, normalizing the output by removing any trailing whitespace characters. [ds]
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+        // Exec 'git rev-parse --show-toplevel' to obtain the absolute path to the top-level directory of the Git repository, parsing away any trailing whitespace to ensure clean path handling. [ds]
         const gitRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+        // Construct the absolute path to the 'hooks' directory by joining the discovered Git directory path with the subfolder name 'hooks'. [ds]
         const hooksDir = path.join(gitDir, 'hooks');
+        // Preemptive check to evaluate if the target 'hooks' directory currently exists in the file system to prevent unnecessary file operations. [ds]
         if (!fs.existsSync(hooksDir)) {
+            // Preventively generate the directory hierarchy if it is missing, passing 'recursive: true' so that parent directories are automatically created alongside the target. [ds]
             fs.mkdirSync(hooksDir, { recursive: true });
         }
 
+        // Initialize the selected execution mode with a default value of '1', which corresponds to a 'Balanced' commenting strategy, pending further user interaction or console settings. [ds]
         let modeChoice = '1';
-        // Prompt user for commenting mode if running in a TTY [ds]
+        // Check the 'isTTY' property to ascertain whether the current process is running in a true interactive terminal environment capable of capturing standard input. [ds]
         if (process.stdout.isTTY) {
+            // Construct an interactive command-line interface, binding the input stream to the standard terminal output to enable typed responses from the executing user. [ds]
             const rl = readline.createInterface({
                 input: process.stdin,
                 output: process.stdout
             });
+            // Define a reusable utility function that wraps the readline interface's question method, encapsulating the asynchronous nature of input polling into a standard resolved Promise. [ds]
             const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
-            // Display commenting mode options to the user [ds]
+            // Print an introductory banner to the standard output, prompting the user to establish the preferred level of conceptual commenting density. [ds]
             console.log('\nSelect default commenting mode for Git commits:');
+            // Display the first selectable option, which represents a balanced hybrid of structural JSDoc blocks and contextual inline variable annotations. [ds]
             console.log('1. Balanced (mix of JSDoc and sparse inline comments)');
+            // Display the second selectable option, which restricts automated formatting solely to high-level JSDoc block comments sitting directly above declared functions. [ds]
             console.log('2. Light (JSDoc block comments above functions only)');
+            // Display the third selectable option, which executes an aggressive generation strategy injecting exhaustive inline step-by-step commentary for every functional line. [ds]
             console.log('3. Full (aggressive inline commenting)');
-            
-            // Loop until a valid mode choice is selected [ds]
+            // Establish a continuous, infinite loop necessary to repeatedly prompt the user for terminal input until a fully valid and non-empty alphanumeric selection is secured. [ds]
             while (true) {
+                // Suspend execution while awaiting the asynchronous resolution of the user's keyboard input, subsequently clearing any leading or trailing accidental spaces from the selection string. [ds]
                 const answer = (await askQuestion('Select (1-3, default: 1): ')).trim();
+                // Perform a boolean evaluation to verify if the received input is either an empty string (which invokes the default state) or strictly matches one of the three valid numerical identifiers. [ds]
                 if (answer === '' || ['1', '2', '3'].includes(answer)) {
+                    // Store the validated input into the 'modeChoice' tracking variable; safely defaulting to '1' automatically if the user provided an empty or whitespace-only string selection. [ds]
                     modeChoice = answer || '1';
+                    // Successfully terminate the infinite validation loop upon securing a valid configuration selection, passing execution to the subsequent argument construction logic. [ds]
                     break;
                 }
                 console.log('Invalid choice. Please select 1, 2, or 3.');
+            // Output an explicit validation error message to the user's terminal to instruct them that the provided numerical format was out of the defined allowable logical bounds. [ds]
             }
+            // Explicitly terminate the active readline interface to cleanly release captured system resources, preventing residual event listeners from blocking the Node.js event loop. [ds]
             rl.close();
         }
 
-        // Determine mode arguments based on user selection [ds]
+        // Declare a string container, initialized with an empty state, intended to house custom command-line flags corresponding to the identified user selection preferences. [ds]
         let modeArgs = '';
+        // Branch execution path if the user dynamically opted into the 'Light' commenting threshold, which dictates minimal architectural styling without deep execution line mapping. [ds]
         if (modeChoice === '2') {
+            // Assign the literal command-line flag '--light', prepending a space to facilitate seamless templating into the future shell script argument string. [ds]
             modeArgs = ' --light';
+        // Alternate conditional execution path triggered if the user selected the 'Full' commenting threshold, indicating a mandate for high-verbosity and deeply inline code descriptions. [ds]
         } else if (modeChoice === '3') {
+            // Assign the literal string value '--full', ensuring a preceding space is present so it consistently formats cleanly as a discrete command-line flag argument. [ds]
             modeArgs = ' --full';
         }
 
-        // Create pre-commit hook script [ds]
+        // Programmatically assemble the complete absolute file path directing toward the executable segment intended for the Git pre-commit lifecycle event hook. [ds]
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
+        // Generate a shell script body utilizing multi-line template literals to define the structural logic required to programmatically intercept and inspect the pre-commit sequence. [ds]
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
 if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
@@ -57,33 +83,67 @@ if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
   npm test || exit 1
 fi
 `;
-        // Write pre-commit hook to file [ds]
-        fs.writeFileSync(preCommitHookPath, preCommitContent);
+        // Check the state of the file system to determine whether a pre-existing pre-commit hook artifact has already been deployed to the repository's primary hooking directory. [ds]
+        if (fs.existsSync(preCommitHookPath)) {
+            // Synchronously read the complete, unmodified contents of the pre-existing hook script and capture it into a string for subsequent signature-based integrity verification. [ds]
+            const existing = fs.readFileSync(preCommitHookPath, 'utf8');
+            // Perform a string mutation check on the existing file body to ascertain if the deployer's specific native hash signature ('# devsplain native pre-commit hook') is entirely absent. [ds]
+            if (!existing.includes('# devsplain native pre-commit hook')) {
+                // If the target signature is absent, signaling that an external custom hook is currently in place, safely concatenate and append the required new native testing execution block to the file's tail. [ds]
+                fs.appendFileSync(preCommitHookPath, '\n' + preCommitContent);
+            } else {
+                // If the required native signature is detected within the existing payload, force a full overwrite of the file object to cleanly restore it to the precise native implementation state. [ds]
+                fs.writeFileSync(preCommitHookPath, preCommitContent);
+            }
+        } else {
+            // Account for the primary cold-start condition where no prior hook file is detected, directly creating the configuration file and persisting the newly templated bash command chain. [ds]
+            fs.writeFileSync(preCommitHookPath, preCommitContent);
+        }
+        // Enclose the specific file permission modification routine within an internal fail-safe error boundary to prevent total deployment aborts upon platform-specific permission barriers. [ds]
         try {
+            // Mutate the file system metadata, overriding standard safety permissions to specifically set executable read/write/execute privileges (octal 0o755) upon the newly written artifact. [ds]
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Path to post-commit script [ds]
+        // Evaluate the script's global root directory path, dynamically applying a standard global regular expression substitution to forcibly normalize any Windows-style backslash path breaks into universal forward slashes. [ds]
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Create post-commit hook script [ds]
+        // Dynamically map the generated environment state to assemble the absolute full path string intended to target and configure the subsequent Git post-commit lifecycle event. [ds]
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
+        // Create a formatted string literal using multi-line template interpolation to construct the actual executable shell command sequence invoking localized script handling at the post-commit stage. [ds]
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
 echo "Auto-generating comments for files in the last commit..."
 node "${postCommitScript}"${modeArgs} || exit 1
 `;
-        // Write post-commit hook to file [ds]
-        fs.writeFileSync(postCommitHookPath, postCommitContent);
+        // Execute a fast synchronous existence check against the post-commit path variable to identify if a command chain is already resident and active in the system's Git hook directory. [ds]
+        if (fs.existsSync(postCommitHookPath)) {
+            // Pull the existing code from the post-commit sequence file stored on the underlying disk format into the active memory context for structural logical inspection and validation. [ds]
+            const existing = fs.readFileSync(postCommitHookPath, 'utf8');
+            // Test the retrieved content payload against the specific hard-coded signature string of the native pipeline to definitively state whether this artifact was previously managed by this system. [ds]
+            if (!existing.includes('# devsplain native post-commit hook')) {
+                // If the identification signature is missing, execute a safety-preserve action by appending the new script array to the end of the file, rather than running a destructive overwrite deletion. [ds]
+                fs.appendFileSync(postCommitHookPath, '\n' + postCommitContent);
+            } else {
+                // If the specific native marker is found, the system assumes full ownership and forces an atomic file rewrite to precisely match the expected execution payload and override missing lines. [ds]
+                fs.writeFileSync(postCommitHookPath, postCommitContent);
+            }
+        } else {
+            // Address the initial initialization state, bypassing the append logic to directly create the target artifact file and persist the customized templated post-commit execution code. [ds]
+            fs.writeFileSync(postCommitHookPath, postCommitContent);
+        }
+        // Instantiate a nested error containing architecture that protects the vital permission update command from cascading uncaught errors and halting subsequent hook deployment operations. [ds]
         try {
+            // Update the file system permissions on the post-commit hook specifically to 0o755 to guarantee that the core operating system is functionally authorized to execute the file as a shell script. [ds]
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Log successful installation of post-commit hook [ds]
+        // Provide immediate visual stdout feedback to the user's command prompt, proving the successful localization and environment writing of the post-commit file within the local repository. [ds]
         console.log(`[devsplain] Git post-commit hook successfully installed at: ${postCommitHookPath}`);
 
-        // Path to devsplain ignore file [ds]
+        // Construct the top-level root path variable by joining the current repository base with the hidden custom generated environment suffix '.devsplainignore'. [ds]
         const ignorePath = path.join(gitRoot, '.devsplainignore');
+        // Define a compact hardcoded array payload storing the foundational and universally recognized developer ignore standard defaults, such as local frameworks, build outputs, and IDE-specific state caches. [ds]
         const defaultIgnoreLines = [
             'node_modules/', '.git/', 'dist/', 'build/', 'out/',
             '.next/', '.nuxt/', '.svelte-kit/',
@@ -91,92 +151,138 @@ node "${postCommitScript}"${modeArgs} || exit 1
             '.vscode/', '.idea/', 'coverage/',
             'tests/', '__tests__/', 'fixtures/'
         ];
-// List of default patterns to ignore [ds]
 
+        // Assemble the exact path coordinates in memory for the root-level standard '.gitignore' file, which has underlying authority and precedence in determining the repository's ignored visual outputs. [ds]
         const gitignorePath = path.join(gitRoot, '.gitignore');
+        // Prepare an empty array structural container for active utilization, designed specifically to intake, parse, and hold the filtered, non-comment active lines from the previously discovered gitignore. [ds]
         let gitignoreLines = [];
+        // Verify at the file-system level whether the conventional and standard root-level '.gitignore' has been explicitly manually created and secured within the exact repository target directory. [ds]
         if (fs.existsSync(gitignorePath)) {
+            // Load the complete raw textual representation of the discovered '.gitignore' configuration into an in-memory variable utilizing the universally resilient default UTF-8 character encoding system. [ds]
             const gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+            // Invoke a high-performance string splitting operation using a strictly matching regular expression explicitly designed to handle both standard newline and cross-platform carriage-return formatting styles. [ds]
             gitignoreLines = gitignoreContent.split(/\r?\n/)
+                // Pipe the generated string array sequentially to a map operation, systematically iterating and applying strict whitespace-parsing to the exact front and rear boundary of each individual detected line. [ds]
                 .map(l => l.trim())
+                // Perform a rigorous structural filter over the parsed array, executing a boolean check to actively strip out and eject any empty strings, fully inert lines, and purely informational documentation comment headers. [ds]
                 .filter(l => l && !l.startsWith('#'));
         }
 
-        // Check if .gitignore file exists [ds]
+        // Execute a protective condition to verify if the target internal hidden '.devsplainignore' file is completely absent to dictate whether to handle a fresh creation or an existing incremental update. [ds]
         if (!fs.existsSync(ignorePath)) {
+            // Compute the exact structural delta by aggressively filtering the raw '.gitignore' payload to physically exclude all internal defaults that the system has already explicitly hardcoded and initialized by design. [ds]
             const gitignoreOnly = gitignoreLines.filter(p => !defaultIgnoreLines.includes(p));
+            // Dynamically synthesize the initial sequential payload by collapsing the hardcoded default ignore array values into a single flat string specifically utilizing standard UNIX newline separators. [ds]
             let content = defaultIgnoreLines.join('\n') + '\n';
+            // Check if the resulting differential payload contains any logically unmatched and entirely novel patterns generated from the operational '.gitignore' system's custom user environment needs. [ds]
             if (gitignoreOnly.length > 0) {
+                // Conditionally chain the newly discovered custom repository rules to the back of the initial payload string, physically interpolating a clear visual banner to indicate external origin. [ds]
                 content += '\n# From .gitignore\n' + gitignoreOnly.join('\n') + '\n';
             }
+            // Resolve the structural assembly and explicitly write the synthesized logical payload representation down to disk to officially establish the root of the hidden configuration file context. [ds]
             fs.writeFileSync(ignorePath, content);
+            // Present an immediate confirmation message directly to the user's terminal prompting, explicitly validating and proving the successful deployment of the new hidden configuration artifact. [ds]
             console.log(`[devsplain] Created .devsplainignore at: ${ignorePath}`);
+            // Evaluate if any custom unique patterns survived the comparative filtering process, specifically serving as the logical trigger to broadcast the exact number of migrated items. [ds]
             if (gitignoreOnly.length > 0) {
+                // Output a localized high-fidelity statistics string dynamically interpolating the exact numerical length of the moved unique patterns from the external environment into the internal file. [ds]
                 console.log(`[devsplain] Merged ${gitignoreOnly.length} pattern(s) from .gitignore into .devsplainignore.`);
             }
         } else {
+            // Navigate into the supplementary update pathway specifically designated for handling active repositories which have already previously established and generated their custom hidden ignore file structure. [ds]
             const existingContent = fs.readFileSync(ignorePath, 'utf8');
+            // Sync-read the fully active existing payload and programmatically pipeline it through the exact same data parsing and filtering sanitation chain used earlier to extract viable active structural rules. [ds]
             const existingLines = existingContent.split(/\r?\n/).map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+            // Dynamically isolate the exact, fully matching strings belonging to the root outer system level that are entirely and systematically missing from the current active internal existing hidden ignore file. [ds]
             const newPatterns = gitignoreLines.filter(p => !existingLines.includes(p));
+            // Perform an evaluation to specifically check if the structural delta extraction operation returned an array populated with even one actively required and missing novel unique operating rule. [ds]
             if (newPatterns.length > 0) {
+                // Formulate a targeted append text structure by concatenating the isolated novel lines linearly, automatically prepending a human-readable informational text category banner underneath. [ds]
                 const appendContent = '\n# From .gitignore\n' + newPatterns.join('\n') + '\n';
+                // Execute a non-destructive, physically conservative file appending command to strictly guarantee that the newly appended array chunk is safely padded down to the final byte of the active text file. [ds]
                 fs.appendFileSync(ignorePath, appendContent);
+                // Broadcast a specifically targeted command prompt notification, accurately surfacing the exact counted quantity of active novel logical rules that were conditionally propagated into the system local file. [ds]
                 console.log(`[devsplain] Merged ${newPatterns.length} new pattern(s) from .gitignore into .devsplainignore.`);
+            // Drop into the else-if fallback branch, logically dictated directly by the complete absence of any missing novel patterns, specifically paired with a confirmation that the source external archive contains items. [ds]
             } else if (gitignoreLines.length > 0) {
+                // Display a purely confirmatory terminal sequence to log the structural immutability state, explicitly projecting and confirming that the system internal system is already completely complete and synchronized. [ds]
                 console.log('[devsplain] .devsplainignore is already up-to-date with .gitignore patterns.');
             }
-        // Handle any errors during hook installation [ds]
         }
 
+    // Enclose the exhaustively complex environment check, write, and setup process inside a robust fail-safe exception container in order to safely capture immediate downstream system interruptions gracefully. [ds]
     } catch (e) {
+        // Intercept the caught high-level exception, force a standardized and targeted warning status into the console, specifically flagging the potential unavailability of native Git CLI command systems. [ds]
         console.warn('Warning: Could not set up Git hooks (not inside a git repository or git command missing).');
         console.warn(e.message);
     }
 }
 
-// Removes Git hooks installed by devsplain [ds]
+/** [ds]
+ * Scans the active Git repository's hook location, identifies the native developers' hook
+ * marker signature, then safely executes a hard unlink process to completely delete
+ * the corresponding lifecycle script, alongside confirming the operational status via
+ * standard terminal output prompting to the executing user.
+*/
 async function removeHooks() {
     try {
+        // Re-invoke the internal Git configuration command to discover the precise filesystem location of the underlying Git state directory utilizing standard cross-platform normalizing output. [ds]
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+        // Synthesize the direct absolute path coordinates required to target the actual, specific folder housing predefined lifecycle event scripts directly operating through the Git process. [ds]
         const hooksDir = path.join(gitDir, 'hooks');
+        // Define an immutable object payload map mapping each specific expected lifecycle event identifier strictly to the exact embedded string signature utilized to prove complete system ownership. [ds]
         const hookSignatures = {
             'pre-commit': '# devsplain native pre-commit hook',
             'post-commit': '# devsplain native post-commit hook'
         };
 
+        // Inception a strict numeric integer tracking variable, structurally initialized to zero, which will exclusively and atomically evaluate and count the total fully successful hard deletions executed. [ds]
         let removed = 0;
-        // Iterate through hook signatures to remove [ds]
+        // Initiate a strictly bounded for...of structural traversal cycle directly over the mapped object entries, dynamically isolating the primary key identifier label and the target string marker value. [ds]
         for (const [hookName, signature] of Object.entries(hookSignatures)) {
+            // Construct the exact, un-escaped absolute target path string natively resolved by joining the isolated sub-folder base coordinate with the actively evaluated specific lifecycle hook name string. [ds]
             const hookPath = path.join(hooksDir, hookName);
+            // Execute a fast, direct filesystem probe to safely verify if the exact isolated file structure actually fully exists and remains physically active on the disk device at the targeted coordinates. [ds]
             if (fs.existsSync(hookPath)) {
+                // If affirmative, read the physical file payload from the disk entirely into string memory specifically utilizing the standard UTF-8 encoding protocol to fully prepare for in-memory deep parsing. [ds]
                 const content = fs.readFileSync(hookPath, 'utf8');
+                // String-search the stored active file memory state to check definitively for the presence of the primary native system hash signature physically marking complete file ownership to this system. [ds]
                 if (content.includes(signature)) {
+                    // Confidently resolve the file pathway and immediately execute a destructive physical unlink operation that entirely and irreversibly removes the target file structure from the local computer's drive. [ds]
                     fs.unlinkSync(hookPath);
+                    // Log an immediate, high-visibility success confirmation to the user prompt area, dynamically interpolating the exact function of the deleted script target alongside its precise absolute storage directory. [ds]
                     console.log(`[devsplain] Removed ${hookName} hook at: ${hookPath}`);
+                    // Safely mutate the previously initialized tracking variable integer by executing a direct increment by one strictly and exclusively upon the completion of undeniably proven targeted file deletion. [ds]
                     removed++;
                 } else {
+                    // Otherwise, navigate to a conservative refusal branch indicating that a conflicting external script resides at the exact same directory coordinates, thereby forcing the process to completely skip physical deletion. [ds]
                     console.log(`[devsplain] Skipping ${hookName}: not installed by devsplain.`);
                 }
             } else {
+                // Navigate to a safe fallback branch addressing an empty slot condition where no structural file system paths are discovered to be actively mapped at the target destination point to evaluate. [ds]
                 console.log(`[devsplain] No ${hookName} hook found at: ${hookPath}`);
             }
         }
 
-        // Log removal of hooks [ds]
+        // Check if the counter tracking variable was mutated from an initial zero state to prove that at least one highly targeted physical file deletion process actively survived through execution cleanly. [ds]
         if (removed > 0) {
+            // Broadcast a localized final success tally update to the user console, dynamically surfacing the exact total count of fully removed lifecycle event operations within the active Git system workspace. [ds]
             console.log(`[devsplain] Successfully removed ${removed} hook(s).`);
         } else {
+            // Display an unconditional, globally quiet status report immediately to the user's active standard output, specifically concluding and notifying that absolutely no conflicting active structured installations were found to delete. [ds]
             console.log('[devsplain] No devsplain hooks were found to remove.');
         }
     } catch (e) {
+        // Intercept any sudden crashes from the deletion cycle, immediately transforming the raw error payload into a targeted and focused console warning to prevent abrupt termination of the parent CLI execution. [ds]
         console.warn('Warning: Could not remove Git hooks (not inside a git repository or git command missing).');
         console.warn(e.message);
     }
 }
 
-// Run installHooks if this script is executed directly [ds]
+// Verify the module's native invocation context by comparing the currently running entry point object literal against the module's own namespace reference to guarantee that this file was the direct core origin trigger. [ds]
 if (require.main === module) {
+    // If validation is completely successful, actively trigger and dispatch the asynchronous installation call responsible for deploying all required Git scripts natively within the currently mapped environment context. [ds]
     installHooks();
 }
-// Export installHooks and removeHooks functions [ds]
+// Relocate both primary action utilities into the locally configured module's exported public interface dictionary to explicitly permit perfectly controlled programmatic execution from strictly external source systems. [ds]
 module.exports = { installHooks, removeHooks };

package/lib/config.js

@@ -4,7 +4,7 @@ const os = require('os');
 const readline = require('readline');
 const configPath = path.join(os.homedir(), '.devsplainrc');
 
-// Asks for secret input from the user [ds]
+/** Prompts the user for sensitive input with hidden characters and raw stdin handling [ds] */
 function askSecret(query) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -22,8 +22,14 @@ function askSecret(query) {
         process.stdout.write('\n');
         rl.close();
         resolve(key);
-      } else if (char === '\u0003') { // Ctrl+C
-        process.exit();
+      } else if (char === '\u0008' || char === '\u007f') {
+        if (key.length > 0) {
+          key = key.slice(0, -1);
+          process.stdout.write('\b \b');
+        }
+      } else if (char === '\u0003') {
+        process.stdin.setRawMode(false);
+        process.exit(130);
       } else {
         key += char;
         process.stdout.write('*');
@@ -33,9 +39,9 @@ function askSecret(query) {
   });
 }
 
-// Migrates old config to the new format [ds]
+/** Migrates legacy single-provider config structure to the new multi-provider format [ds] */
 function migrateConfig(oldConfig) {
-  if (oldConfig.provider && !oldConfig.providers) {
+  if (oldConfig && typeof oldConfig === 'object' && oldConfig.provider && !oldConfig.providers) {
     return {
       activeProvider: oldConfig.provider,
       providers: {
@@ -51,7 +57,7 @@ function migrateConfig(oldConfig) {
   return oldConfig;
 }
 
-// Gets the config, either from environment variables, the config file, or by prompting the user [ds]
+/** Resolves config from environment variables, file storage, or interactive wizard setup [ds] */
 async function getConfig(forceWizard = false) {
   if (process.env.DEVSPLAIN_API_KEY || process.env.DEVSPLAIN_PROVIDER) {
     const provider = process.env.DEVSPLAIN_PROVIDER || 'gemini';
@@ -71,11 +77,10 @@ async function getConfig(forceWizard = false) {
       const rawData = fs.readFileSync(configPath, 'utf8');
       fileConfig = migrateConfig(JSON.parse(rawData));
     } catch (e) {
-      // Ignored, file might be corrupted
     }
   }
 
-  if (!fileConfig || forceWizard) {
+  if (!fileConfig || !fileConfig.activeProvider || !fileConfig.providers || !fileConfig.providers[fileConfig.activeProvider] || forceWizard) {
     let rl = readline.createInterface({
       input: process.stdin,
       output: process.stdout
@@ -98,7 +103,6 @@ async function getConfig(forceWizard = false) {
           console.log(`${i + 1}. ${p}${isActive}`);
         });
         console.log(`\n${savedProviders.length + 1}. Add/Configure a different provider`);
-        
         const c = await askQuestion(`Select (1-${savedProviders.length + 1}): `);
         const idx = parseInt(c) - 1;
 
@@ -179,7 +183,6 @@ async function getConfig(forceWizard = false) {
           provider = providerToConfig;
           const old = config.providers[provider];
           baseUrl = old.baseUrl;
-          
           let defaultModel = old.model;
           const customModel = await askQuestion(`Model name (press Enter for default '${defaultModel}'): `);
           model = customModel.trim() || defaultModel;
@@ -248,12 +251,11 @@ async function getConfig(forceWizard = false) {
             confirmed = true;
             break;
           } else if (confirm === 'n' || confirm === 'no') {
-            break; // Start over loop
+            break;
           }
           console.log("Invalid choice. Please enter 'y' or 'n'.");
         }
       } else {
-        // User just selected an existing provider and didn't want to update it
         config.activeProvider = providerToConfig;
         console.log(`\nSwitched active provider to ${config.activeProvider}.`);
         confirmed = true;
@@ -274,9 +276,10 @@ async function getConfig(forceWizard = false) {
       ...config.providers[config.activeProvider]
     };
   } else {
+    const active = fileConfig.providers[fileConfig.activeProvider] || {};
     return {
       provider: fileConfig.activeProvider,
-      ...fileConfig.providers[fileConfig.activeProvider]
+      ...active
     };
   }
 }

package/lib/llm.js

@@ -1,82 +1,151 @@
-// Asynchronously fetches data from the specified URL with a retry mechanism [ds]
+/** [ds]
+ * Sends an HTTP request with automatic retry logic and timeout management.
+ * @param {string} url - The target URL.
+ * @param {object} options - Fetch options including method, headers, and body.
+ * @param {number} maxRetries - Maximum number of retry attempts.
+ * @param {number} initialDelay - Initial delay in milliseconds for exponential backoff.
+ * @returns {Promise<Response>} - Returns the successful Response object.
+*/
 async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000) {
+    // Initialize a variable to store the last encountered error for potential re-throwing [ds]
     let lastError;
-    // Loop through each attempt, up to the maximum number of retries [ds]
+    // Enter a retry loop that executes up to 'maxRetries' times [ds]
     for (let attempt = 0; attempt < maxRetries; attempt++) {
+        // Create an AbortController to manually trigger request timeouts [ds]
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 15000);
+        // Schedule an abort action after 45 seconds to prevent hanging connections [ds]
+        const timeoutId = setTimeout(() => controller.abort(), 45000);
+        // Begin a try block to handle potential network or processing exceptions [ds]
         try {
+            // Execute the fetch request, passing the URL and options with the abort signal [ds]
             const response = await fetch(url, {
+                // Spread existing options into the fetch configuration [ds]
                 ...options,
+                // Attach the abort signal to allow external cancellation [ds]
                 signal: controller.signal
             });
+            // Clear the timeout timer to clean up the abort signal since the request completed [ds]
             clearTimeout(timeoutId);
+            // Validate that a response object was actually received [ds]
+            if (!response) {
+                // Throw a custom error if the response is missing or null [ds]
+                throw new Error("No response received from fetch");
+            }
+            // Check if the HTTP response indicates success (2xx status) [ds]
             if (response.ok) {
+                // Return the response immediately upon successful HTTP completion [ds]
                 return response;
             }
+            // Identify transient errors: 429 (Too Many Requests) or 5xx (Server Errors) [ds]
             if (response.status === 429 || (response.status >= 500 && response.status < 600)) {
+                // Store the transient error to trigger a retry in the next loop iteration [ds]
                 lastError = new Error(`HTTP Error ${response.status}: ${response.statusText}`);
             } else {
+                // For non-transient errors (4xx), return the response directly to let caller handle [ds]
                 return response;
             }
+        // Catch any synchronous errors thrown during the await or setup [ds]
         } catch (err) {
+            // Clear the timeout timer to prevent memory leaks on failure [ds]
             clearTimeout(timeoutId);
+            // Check if the error was caused by the manual timeout abort [ds]
             if (err.name === 'AbortError') {
-                lastError = new Error("Request timed out after 15 seconds");
+                // Convert the AbortError into a descriptive timeout message [ds]
+                lastError = new Error("Request timed out after 45 seconds");
             } else {
+                // Store any other standard errors for potential retry logic [ds]
                 lastError = err;
             }
         }
 
+        // Check if more retry attempts remain before the final try [ds]
         if (attempt < maxRetries - 1) {
+            // Calculate exponential backoff delay: base delay multiplied by 2 to the power of attempts [ds]
             const backoffDelay = initialDelay * Math.pow(2, attempt);
+            // Log a warning to the console indicating a retry is occurring [ds]
             console.warn(`[devsplain] AI request failed. Retrying in ${backoffDelay}ms... (Attempt ${attempt + 1}/${maxRetries})`);
+            // Pause execution for the calculated backoff duration before retrying [ds]
             await new Promise(resolve => setTimeout(resolve, backoffDelay));
         }
     }
+    // Re-throw the last error if all retry attempts have been exhausted [ds]
     throw lastError;
 }
 
-// Retrieves comments for the given code, language, and configuration [ds]
+/** [ds]
+ * Orchestrate code documentation by calling various AI providers.
+ * Handles prompt construction, provider-specific API calls, and response parsing.
+ * @param {string} code - The source code to analyze.
+ * @param {string} language - The programming language and file extension.
+ * @param {object} config - Provider configuration details.
+ * @param {string} mode - Documentation density mode ('default', 'light', 'full', 'clean').
+ * @returns {Promise<Array>} - Array of comment insertion objects.
+*/
 async function getComments(code, language, config, mode = 'default') {
+    // Split source code into an array of lines, handling Windows and Unix newline styles [ds]
     const lines = code.split(/\r?\n/);
+    // Prepend line numbers to each line to help the AI map comments to specific locations [ds]
     const numberedCode = lines.map((line, index) => `${index + 1}: ${line}`).join('\n');
 
-    // Extract the file extension from the language string [ds]
+    // Extract the file extension using a regular expression [ds]
     const extMatch = language.match(/\.[0-9a-z]+$/i);
+    // Normalize the extension to lowercase or default to empty string if missing [ds]
     const ext = extMatch ? extMatch[0].toLowerCase() : '';
+    // Determine if the language is Python [ds]
     const isPython = ext === '.py';
-    const isRubyOrShell = ['.rb', '.sh', '.php'].includes(ext);
+    // Determine if the language is Ruby or Shell Script [ds]
+    const isRubyOrShell = ['.rb', '.sh'].includes(ext);
+    // Determine if the language is HTML-based (HTML, Vue, Svelte) [ds]
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext);
+    // Determine if the language is CSS or SCSS [ds]
+    const isCss = ['.css', '.scss'].includes(ext);
+    // Determine if the language is SQL [ds]
     const isSql = ext === '.sql';
-    
-    // Define the single-line comment token and examples [ds]
+    // Initialize comment syntax tokens for standard C-like languages [ds]
     let singleLineToken = '//';
     let blockExample = '/** Calculates the total price */';
     let inlineExample = '// Check for null values';
 
+    // Adjust comment syntax for Python and Shell-based languages [ds]
     if (isPython || isRubyOrShell) {
         singleLineToken = '#';
         blockExample = '# Calculates the total price';
         inlineExample = '# Check for null values';
+    // Adjust comment syntax for HTML template languages [ds]
     } else if (isHTML) {
         singleLineToken = '<!--';
         blockExample = '<!-- Calculates the total price -->';
         inlineExample = '<!-- Check for null values -->';
+    // Adjust comment syntax for CSS stylesheets [ds]
+    } else if (isCss) {
+        singleLineToken = '/*';
+        blockExample = '/* Calculates the total price */';
+        inlineExample = '/* Check for null values */';
+    // Adjust comment syntax for SQL queries [ds]
     } else if (isSql) {
         singleLineToken = '--';
         blockExample = '-- Calculates the total price';
         inlineExample = '-- Check for null values';
     }
 
-    // Provide instructions based on the mode [ds]
+    // Set default prompting instruction for standard documentation [ds]
     let instruction = `Provide block comments above functions and sparse inline comments for complex logic.`;
+    // Modify instruction if minimal documentation is requested [ds]
     if (mode === 'light') {
         instruction = `Provide ONLY block comments above functions. Keep it minimal.`;
+    // Modify instruction for exhaustive step-by-step documentation mode [ds]
     } else if (mode === 'full') {
         instruction = `Provide highly detailed block comments above functions, and exhaustive step-by-step inline comments explaining every conditional branch, loop, variable assignment, and logical block inside function bodies. Do not be sparse; explain the code's execution flow in detail.`;
     }
 
+    // Define a placeholder rule for comment syntax restrictions [ds]
+    let rule5 = `5. IMPORTANT: Use ONLY ${singleLineToken} for comments. DO NOT use docstrings or multi-line string literals like """ or ''' for comments.`;
+    // Override the syntax rule specifically for CSS files [ds]
+    if (isCss) {
+        rule5 = `5. IMPORTANT: In CSS/SCSS, you MUST use /* ... */ for comments. DO NOT use // comments under any circumstances.`;
+    }
+
+    // Construct the full prompt combining rules, examples, and the numbered source code [ds]
     let prompt = `
 You are a code documentation engine. Analyze the following ${language} code which has line numbers prepended to it.
 ${instruction}
@@ -86,7 +155,7 @@ CRITICAL RULES:
 2. Each object must have exactly two properties: "line" (the integer line number where the comment should be inserted ABOVE) and "comment" (the text of the comment itself).
 3. Do NOT include the original code in your response.
 4. If no comments are needed, return an empty array: [].
-5. IMPORTANT: Use ONLY ${singleLineToken} for comments. DO NOT use docstrings or multi-line string literals like """ or ''' for comments.
+${rule5}
 
 Example Output:
 [
@@ -98,13 +167,18 @@ Here is the source code:
 ${numberedCode}
     `.trim();
 
+    // Initialize a variable to hold the raw text output from the AI provider [ds]
     let textResponse = "";
 
-    // Handle API requests based on the provider [ds]
+    // Branch to handle the Google Gemini API provider [ds]
     if (config.provider === 'gemini') {
+        // Construct the Google Gemini API endpoint URL with model and API key [ds]
         const url = `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent?key=${config.apiKey}`;
+        // Declare a variable to store the parsed API response [ds]
         let data;
+        // Begin error handling for the Gemini API call [ds]
         try {
+            // Send the POST request to the Gemini API with the constructed prompt [ds]
             const response = await fetchWithRetry(url, {
                 method: 'POST',
                 headers: { 
@@ -114,19 +188,37 @@ ${numberedCode}
                     "contents": [{ "parts": [{ "text": prompt }] }]
                 })
             });
+            // Parse the JSON response body from the Gemini service [ds]
             data = await response.json();
+        // Wrap network or fetch errors in a standard descriptive error [ds]
         } catch (error) {
-            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            throw new Error(`AI Provider Request Failed: ${error.message}`);
         }
+        // Check if the Gemini response contains an error object [ds]
         if (data.error) {
-            throw new Error(`API Error: ${data.error.message}`);
+            // Extract the human-readable error message from the Google-specific structure [ds]
+            const msg = data.error.message || (typeof data.error === 'string' ? data.error : JSON.stringify(data.error));
+            // Throw a normalized error based on the API error details [ds]
+            throw new Error(`API Error: ${msg}`);
+        }
+        // Validate that the Gemini response structure contains the expected content [ds]
+        if (!data.candidates || !data.candidates[0] || !data.candidates[0].content || !data.candidates[0].content.parts || !data.candidates[0].content.parts[0]) {
+            // Capture the finish reason to provide context for empty content errors [ds]
+            const reason = data.candidates?.[0]?.finishReason || 'Unknown error';
+            // Throw an error indicating the AI returned no usable content [ds]
+            throw new Error(`AI Provider returned no content (finish reason: ${reason})`);
         }
+        // Extract the raw text content from the Gemini response candidates [ds]
         textResponse = data.candidates[0].content.parts[0].text;
+    // Branch to handle the Anthropic Claude API provider [ds]
     } else if (config.provider === 'claude') {
-        // Handle Claude API requests [ds]
+        // Construct the Anthropic API endpoint URL [ds]
         const url = `${config.baseUrl}/v1/messages`;
+        // Declare a variable to store the parsed Anthropic API response [ds]
         let data;
+        // Begin error handling for the Anthropic API call [ds]
         try {
+            // Send the POST request to Anthropic with version headers and API key [ds]
             const response = await fetchWithRetry(url, {
                 method: 'POST',
                 headers: {
@@ -143,97 +235,198 @@ ${numberedCode}
                     }]
                 })
             });
+            // Parse the JSON response body from the Anthropic service [ds]
             data = await response.json();
+        // Wrap network or fetch errors in a standard descriptive error [ds]
         } catch (error) {
-            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            throw new Error(`AI Provider Request Failed: ${error.message}`);
         }
+        // Check if the Anthropic response contains an error object [ds]
         if (data.error) {
-            throw new Error(`API Error: ${data.error.message}`);
+            // Extract the human-readable error message from the Anthropic response [ds]
+            const msg = data.error.message || (typeof data.error === 'string' ? data.error : JSON.stringify(data.error));
+            // Throw a normalized error based on the API error details [ds]
+            throw new Error(`API Error: ${msg}`);
         }
+        // Validate that the Anthropic response structure contains valid text content [ds]
+        if (!data.content || !data.content[0] || typeof data.content[0].text !== 'string') {
+            // Throw an error with the raw JSON if the structure is unexpected [ds]
+            throw new Error(`AI Provider returned an unexpected response structure: ${JSON.stringify(data)}`);
+        }
+        // Extract the text content from the first message block [ds]
         textResponse = data.content[0].text;
     } 
-    // Handle other API requests [ds]
+    // Default branch for OpenAI-compatible APIs (OpenAI, Groq, etc.) [ds]
     else {
+        // Construct the OpenAI-compatible chat completions endpoint [ds]
         const url = `${config.baseUrl}/v1/chat/completions`;
+        // Declare a variable to store the parsed OpenAI-compatible response [ds]
         let data;
 
+        // Initialize the request body structure with model and message content [ds]
+        const reqBody = { 
+            "model": config.model, 
+            "messages": [{ 
+                "role": "user", 
+                "content": prompt 
+            }] 
+        };
+        // Apply specific token limits for Groq provider to avoid issues [ds]
+        if (config.provider === 'groq') {
+            reqBody.max_tokens = 1000;
+        // Apply default high token limit for other OpenAI-compatible providers [ds]
+        } else {
+            reqBody.max_tokens = 8192;
+        }
+
+        // Begin error handling for the OpenAI-compatible API call [ds]
         try {
+            // Send the POST request with Bearer token authentication [ds]
             const response = await fetchWithRetry(url, {
                 method: 'POST',
                 headers: { 
                     'Content-Type': 'application/json', 
                     'Authorization': `Bearer ${config.apiKey}` 
                 },
-                body: JSON.stringify({ 
-                    "model": config.model, 
-                    "messages": [{ 
-                        "role": "user", 
-                        "content": prompt 
-                    }] 
-                })
+                body: JSON.stringify(reqBody)
             });
+            // Parse the JSON response body from the OpenAI-compatible service [ds]
             data = await response.json();
+        // Wrap network or fetch errors in a standard descriptive error [ds]
         } catch (error) {
-            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            throw new Error(`AI Provider Request Failed: ${error.message}`);
         }
+        // Check if the OpenAI-compatible response contains an error object [ds]
         if (data.error) {
-            throw new Error(`API Error: ${data.error.message}`);
+            // Extract the human-readable error message from the OpenAI error structure [ds]
+            const msg = data.error.message || (typeof data.error === 'string' ? data.error : JSON.stringify(data.error));
+            // Throw a normalized error based on the API error details [ds]
+            throw new Error(`API Error: ${msg}`);
+        }
+        // Validate that the OpenAI response structure contains a valid message object [ds]
+        if (!data.choices || !data.choices[0] || !data.choices[0].message || typeof data.choices[0].message.content !== 'string') {
+            // Throw an error with the raw JSON if the structure is unexpected [ds]
+            throw new Error(`AI Provider returned an unexpected response structure: ${JSON.stringify(data)}`);
         }
+        // Extract the text content from the first choice's message [ds]
         textResponse = data.choices[0].message.content;
     }
 
+    // Remove leading and trailing whitespace from the AI text output [ds]
     let cleanText = textResponse.trim();
+    // Locate the starting index of the JSON array [ds]
     const start = cleanText.indexOf('[');
+    // Locate the ending index of the JSON array [ds]
     const end = cleanText.lastIndexOf(']');
-    if (start !== -1 && end !== -1 && end >= start) {
-        cleanText = cleanText.substring(start, end + 1);
+    // Check if a JSON array was actually found in the text [ds]
+    if (start !== -1) {
+        // Validate that the end index exists and comes after the start index [ds]
+        if (end !== -1 && end >= start) {
+            // Slice the text to contain only the JSON array portion [ds]
+            cleanText = cleanText.substring(start, end + 1);
+        } else {
+            // If ']' is missing, look for the last closing brace to fix truncated JSON [ds]
+            const lastBrace = cleanText.lastIndexOf('}');
+            // Ensure the found brace is actually within the current text segment [ds]
+            if (lastBrace > start) {
+                // Manually append the missing closing bracket to make valid JSON [ds]
+                cleanText = cleanText.substring(start, lastBrace + 1) + ']';
+            }
+        }
     }
 
+    // Declare a variable to store the parsed JSON object [ds]
     let parsed;
+    // Attempt to parse the cleaned text string into a JavaScript object [ds]
     try {
-        // Attempt to parse the response as JSON [ds]
+        // Execute the JSON parsing operation [ds]
         parsed = JSON.parse(cleanText);
+    // Catch parsing errors if the text is malformed [ds]
     } catch (e) {
+        // Throw a descriptive error including the raw response for debugging [ds]
         throw new Error(`Parsing Error: Failed to parse LLM response as JSON. Raw response was:\n${textResponse}`);
     }
 
+    // Validate that the parsed result is a JavaScript array [ds]
     if (!Array.isArray(parsed)) {
+        // Throw an error if the top-level JSON structure is not an array [ds]
         throw new Error("Schema Error: LLM response is not a JSON array.");
     }
 
-    // Validate the parsed response [ds]
+    // Iterate over each comment object in the parsed array for validation [ds]
     for (const item of parsed) {
+        // Verify that each item is a real object and not null or a primitive [ds]
         if (typeof item !== 'object' || item === null) {
+            // Throw a schema error for invalid object types [ds]
             throw new Error("Schema Error: Array elements must be objects.");
         }
+        // Validate that the 'line' property is a positive integer [ds]
         if (!Number.isInteger(item.line) || item.line <= 0) {
+            // Throw a schema error for invalid line numbers [ds]
             throw new Error("Schema Error: 'line' must be a positive integer.");
         }
 
+        // Enforce specific schema rules for data cleaning mode [ds]
         if (mode === 'clean') {
+            // Ensure the 'action' property is 'delete' if in clean mode [ds]
             if (item.action !== 'delete') {
+                // Throw a schema error for invalid actions in clean mode [ds]
                 throw new Error("Schema Error: 'action' must be 'delete' in clean mode.");
             }
+        // Handle standard documentation modes that require comment text [ds]
         } else {
+            // Verify that the 'comment' property exists and is a string [ds]
             if (typeof item.comment !== 'string') {
+                // Throw a schema error if comment text is missing or not a string [ds]
                 throw new Error("Schema Error: 'comment' must be a string.");
             }
 
+            // Normalize the comment text by trimming whitespace [ds]
             const trimmedComment = item.comment.trim();
-            const startsWithCommentMarker = 
-                trimmedComment.startsWith('//') || 
-                trimmedComment.startsWith('/*') || 
-                trimmedComment.startsWith('#') ||
-                trimmedComment.startsWith('<!--') ||
-                trimmedComment.startsWith('--');
-
-            if (!startsWithCommentMarker) {
-                throw new Error(`Security Error: Comment on line ${item.line} does not start with a valid comment character sequence. Rejected: ${trimmedComment}`);
+            // Split the comment into lines to validate syntax per line [ds]
+            const commentLines = trimmedComment.split(/\r?\n/);
+            // Track whether we are currently inside a block comment [ds]
+            let inBlock = false;
+            // Loop through each line of the comment string [ds]
+            for (const cl of commentLines) {
+                // Trim leading/trailing whitespace from the current comment line [ds]
+                const tcl = cl.trim();
+                // Skip empty lines during validation [ds]
+                if (!tcl) continue;
+                // Check if this line is part of the continuation of a block comment [ds]
+                if (inBlock) {
+                    // Detect if the line closes a block comment (CSS/HTML style) [ds]
+                    if (tcl.includes('*/') || tcl.includes('-->')) {
+                        // Mark block comment state as false if a closing marker is found [ds]
+                        inBlock = false;
+                    }
+                    // Skip validation for lines inside a block comment [ds]
+                    continue;
+                }
+                // Check if the line starts with a valid comment marker [ds]
+                const startsWithMarker = 
+                    tcl.startsWith('//') || 
+                    tcl.startsWith('/*') || 
+                    tcl.startsWith('*') || 
+                    tcl.startsWith('#') || 
+                    tcl.startsWith('<!--') || 
+                    tcl.startsWith('--');
+                // Throw a strict security error if a line lacks a comment prefix [ds]
+                if (!startsWithMarker) {
+                    throw new Error(`Security Error: Comment on line ${item.line} contains invalid non-comment line: "${tcl}"`);
+                }
+                // Detect if a line opens a block comment without closing it [ds]
+                if ((tcl.startsWith('/*') && !tcl.includes('*/')) || (tcl.startsWith('<!--') && !tcl.includes('-->'))) {
+                    // Set the block comment state to true for subsequent line processing [ds]
+                    inBlock = true;
+                }
             }
         }
     }
 
+    // Return the fully validated and parsed array of comments [ds]
     return parsed;
 }
 
+// Export the main function for use by external modules [ds]
 module.exports = { getComments };

package/package.json

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