minovative-mind-cli 2.13.3 → 2.13.4

package/dist/services/orchestration/scopedTools.js

@@ -1,7 +1,9 @@
 import path from 'path';
 import { executeTool, getToolDeclarations as getBaseToolDeclarations } from '../agent-tools.js';
 import { MessageBus } from './messageBus.js';
+import { computeReadCacheKey } from './readCache.js';
 import { resolveAndValidateMultiWorkspacePath } from '../../utils/pathSecurity.js';
+import { recordFileRead } from '../../utils/fileReadGuard.js';
 import { debugLog } from '../../utils/logger.js';
 /**
  * Resolves a file path to its canonical absolute path for lock registry keying,
@@ -83,7 +85,7 @@ export function getScopedToolDeclarations() {
 /**
  * Executes a tool within the sub-agent execution boundary.
  * Handles concurrency locking for file-mutating operations, sends progress
- * notifications to the orchestrator, and logs activity to the message bus.
+ * notifications to the orchestrator, checks per-agent read caches, and logs activity to the message bus.
  *
  * @param name - Tool function name
  * @param args - Tool arguments object
@@ -94,8 +96,9 @@ export function getScopedToolDeclarations() {
  * @param onProgress - Callback to notify parent of sub-agent progress
  * @param options - Optional sub-path auto-focus and override configuration
  * @param taskScope - Optional task scope metadata (targetFiles, dependsOn)
+ * @param readCache - Optional per-agent in-memory file read cache
  */
-export async function executeScopedTool(name, args, workspaceRoot, agentId, bus, locks, onProgress, options, taskScope) {
+export async function executeScopedTool(name, args, workspaceRoot, agentId, bus, locks, onProgress, options, taskScope, readCache) {
     // Update heartbeat so the orchestrator knows we are making progress
     onProgress();
     const timestamp = Date.now();
@@ -148,48 +151,108 @@ export async function executeScopedTool(name, args, workspaceRoot, agentId, bus,
                 semanticSignals: MessageBus.formatSignals(unread.signals),
             };
         }
-        // ─── Standard Tool Execution with Locking ────────────────────────
-        // Handle lock acquisition for write-oriented tools
-        let lockedFile = null;
-        let diffContext = null;
-        if (name === 'write_file' || name === 'modify_file' || name === 'delete_file') {
-            const rawPath = args.filePath;
-            if (rawPath) {
-                lockedFile = resolveCanonicalLockPath(workspaceRoot, rawPath, options);
-                debugLog(`Agent "${agentId}" requesting lock for "${lockedFile}" (raw: "${rawPath}", tool: ${name})`);
-                onProgress(`waiting for lock on ${path.basename(lockedFile)}...`);
-                const lockRes = await locks.acquire(lockedFile, agentId);
-                onProgress(`acquired lock, executing...`);
-                diffContext = lockRes.previousDiff;
-                if (lockRes.forceReleased) {
-                    debugLog(`Agent "${agentId}" got forced lock on "${lockedFile}" (previous owner stalled)`);
-                }
+        // ─── Standard Tool Execution with Locking & Caching ──────────────
+        // Check read cache for read_file operations
+        let cacheHit = false;
+        let cacheKey = '';
+        if (name === 'read_file' && readCache && args?.filePath) {
+            cacheKey = computeReadCacheKey(args.filePath, args.startLine, args.endLine, args.targetElements);
+            if (readCache.has(cacheKey)) {
+                const cached = readCache.get(cacheKey);
+                recordFileRead(args.filePath);
+                result = {
+                    output: cached.text,
+                    ...(cached.inlineData ? { inlineData: cached.inlineData } : {}),
+                };
+                cacheHit = true;
             }
         }
-        else if (name === 'rename_file') {
-            const rawPath = args.sourcePath;
-            if (rawPath) {
-                lockedFile = resolveCanonicalLockPath(workspaceRoot, rawPath, options);
-                debugLog(`Agent "${agentId}" requesting lock for "${lockedFile}" (raw: "${rawPath}", tool: ${name})`);
-                onProgress(`waiting for lock on ${path.basename(lockedFile)}...`);
-                const lockRes = await locks.acquire(lockedFile, agentId);
-                onProgress(`acquired lock, executing...`);
-                diffContext = lockRes.previousDiff;
-                if (lockRes.forceReleased) {
-                    debugLog(`Agent "${agentId}" got forced lock on "${lockedFile}" (previous owner stalled)`);
+        if (!cacheHit) {
+            // Handle lock acquisition for write-oriented tools
+            let lockedFile = null;
+            let diffContext = null;
+            if (name === 'write_file' || name === 'modify_file' || name === 'delete_file') {
+                const rawPath = args.filePath;
+                if (rawPath) {
+                    lockedFile = resolveCanonicalLockPath(workspaceRoot, rawPath, options);
+                    debugLog(`Agent "${agentId}" requesting lock for "${lockedFile}" (raw: "${rawPath}", tool: ${name})`);
+                    onProgress(`waiting for lock on ${path.basename(lockedFile)}...`);
+                    const lockRes = await locks.acquire(lockedFile, agentId);
+                    onProgress(`acquired lock, executing...`);
+                    diffContext = lockRes.previousDiff;
+                    if (lockRes.forceReleased) {
+                        debugLog(`Agent "${agentId}" got forced lock on "${lockedFile}" (previous owner stalled)`);
+                    }
                 }
             }
-        }
-        // Execute the underlying standard tool
-        try {
-            result = await executeTool(workspaceRoot, name, args);
-            // If we got a file lock and had context from a previous writer, we should 
-            // inject that diff info back into the agent's tool return payload so it 
-            // knows someone else changed the file while it was queued.
-            if (diffContext && typeof result === 'object' && result !== null) {
-                result._orchestrationWarning = `NOTICE: Another agent modified this file while you were waiting. Diff context: ${diffContext}`;
+            else if (name === 'rename_file') {
+                const rawPath = args.sourcePath;
+                if (rawPath) {
+                    lockedFile = resolveCanonicalLockPath(workspaceRoot, rawPath, options);
+                    debugLog(`Agent "${agentId}" requesting lock for "${lockedFile}" (raw: "${rawPath}", tool: ${name})`);
+                    onProgress(`waiting for lock on ${path.basename(lockedFile)}...`);
+                    const lockRes = await locks.acquire(lockedFile, agentId);
+                    onProgress(`acquired lock, executing...`);
+                    diffContext = lockRes.previousDiff;
+                    if (lockRes.forceReleased) {
+                        debugLog(`Agent "${agentId}" got forced lock on "${lockedFile}" (previous owner stalled)`);
+                    }
+                }
+            }
+            // Execute the underlying standard tool
+            try {
+                result = await executeTool(workspaceRoot, name, args);
+                // If read_file succeeded, store in readCache
+                if (name === 'read_file' &&
+                    readCache &&
+                    cacheKey &&
+                    result &&
+                    !result.error &&
+                    typeof result.output === 'string') {
+                    readCache.set(cacheKey, {
+                        text: result.output,
+                        inlineData: result.inlineData,
+                    });
+                }
+                // If a file was modified/written/deleted/renamed, invalidate readCache entries for affected file(s)
+                if (readCache) {
+                    if (name === 'write_file' || name === 'modify_file' || name === 'delete_file') {
+                        if (args?.filePath) {
+                            readCache.invalidate(args.filePath);
+                        }
+                    }
+                    else if (name === 'rename_file') {
+                        if (args?.sourcePath)
+                            readCache.invalidate(args.sourcePath);
+                        if (args?.targetPath)
+                            readCache.invalidate(args.targetPath);
+                    }
+                }
+                // If we got a file lock and had context from a previous writer, we should 
+                // inject that diff info back into the agent's tool return payload so it 
+                // knows someone else changed the file while it was queued.
+                if (diffContext && typeof result === 'object' && result !== null) {
+                    result._orchestrationWarning = `NOTICE: Another agent modified this file while you were waiting. Diff context: ${diffContext}`;
+                }
+                // In-band relevance-gated urgent signals (warnings, targeted requests, or upstream completions)
+                if (typeof result === 'object' && result !== null && typeof bus?.peekUrgentSignals === 'function') {
+                    const urgentSignals = bus.peekUrgentSignals(agentId, taskScope);
+                    if (urgentSignals && urgentSignals.length > 0) {
+                        result._orchestrationNotice = MessageBus.formatSignals(urgentSignals);
+                    }
+                }
+            }
+            finally {
+                // Release the lock if we grabbed one
+                if (lockedFile) {
+                    // We do a simple release. The actual diff context extraction happens at the orchestrator 
+                    // layer during verification, but we release immediately to unblock others.
+                    locks.release(lockedFile, agentId, `Action: ${name} completed`);
+                }
             }
-            // In-band relevance-gated urgent signals (warnings, targeted requests, or upstream completions)
+        }
+        else {
+            // For cache hit, also check urgent signals from bus if needed
             if (typeof result === 'object' && result !== null && typeof bus?.peekUrgentSignals === 'function') {
                 const urgentSignals = bus.peekUrgentSignals(agentId, taskScope);
                 if (urgentSignals && urgentSignals.length > 0) {
@@ -197,14 +260,6 @@ export async function executeScopedTool(name, args, workspaceRoot, agentId, bus,
                 }
             }
         }
-        finally {
-            // Release the lock if we grabbed one
-            if (lockedFile) {
-                // We do a simple release. The actual diff context extraction happens at the orchestrator 
-                // layer during verification, but we release immediately to unblock others.
-                locks.release(lockedFile, agentId, `Action: ${name} completed`);
-            }
-        }
         // ─── Formatting Log Outputs ──────────────────────────────────────
         if (name === 'write_file' || name === 'modify_file') {
             targetDesc = args.filePath;
@@ -213,9 +268,9 @@ export async function executeScopedTool(name, args, workspaceRoot, agentId, bus,
         }
         else if (name === 'read_file') {
             targetDesc = args.filePath;
-            actionDesc = 'Read';
-            const len = typeof result === 'string' ? result.length : (result.fileContents?.length || 0);
-            resultSummary = `${len} chars`;
+            actionDesc = cacheHit ? 'Read (cached)' : 'Read';
+            const len = typeof result === 'string' ? result.length : (result.fileContents?.length || (result.output ? result.output.length : 0));
+            resultSummary = `${len} chars${cacheHit ? ' (cached)' : ''}`;
         }
         else if (name === 'run_command') {
             targetDesc = args.command;

package/dist/services/orchestration/subAgent.d.ts

@@ -62,6 +62,7 @@ export declare class SubAgentRunner {
     private inputTokens;
     private lastHeartbeat;
     private outputTokens;
+    private readonly readCache;
     /**
      * Updates the heartbeat. Passed to `executeScopedTool` to ensure the agent
      * isn't marked as stalled while performing long-running commands.

package/dist/services/orchestration/subAgent.js

@@ -6,6 +6,7 @@
  */
 import { ProxyChatSession, getGlobalActiveModel } from '../ai.js';
 import { GEMINI_MODELS, MAX_OUTPUT_TOKENS } from '../../utils/config.js';
+import { ReadCache } from './readCache.js';
 import { executeScopedTool, getScopedToolDeclarations } from './scopedTools.js';
 import { debugLog } from '../../utils/logger.js';
 import { runWithAgentId } from '../../utils/asyncContext.js';
@@ -140,6 +141,7 @@ export class SubAgentRunner {
     inputTokens = 0;
     lastHeartbeat = Date.now();
     outputTokens = 0;
+    readCache = new ReadCache();
     /**
      * Updates the heartbeat. Passed to `executeScopedTool` to ensure the agent
      * isn't marked as stalled while performing long-running commands.
@@ -169,6 +171,10 @@ export class SubAgentRunner {
             temperature: 0.3, // Lower temperature for more focused execution
             topP: 0.95,
             topK: 40,
+        }, {
+            functionCallingConfig: {
+                mode: 'ANY',
+            },
         });
     }
     /**
@@ -249,15 +255,30 @@ export class SubAgentRunner {
                 // Tool Loop
                 const MAX_TURNS = Infinity;
                 let turns = 0;
+                let textRetryCount = 0;
+                const MAX_TEXT_RETRIES = 2;
+                let hasExecutedAnyTool = false;
                 while (turns < MAX_TURNS && !crashed && !signal.aborted) {
                     this.pingHeartbeat();
                     const calls = turnResult.response.functionCalls();
-                    // If the model stopped calling tools, it is done
+                    // If the model stopped calling tools, check if it executed any tools or exited prematurely on Turn 1
                     if (!calls || calls.length === 0) {
+                        if (!hasExecutedAnyTool && textRetryCount < MAX_TEXT_RETRIES) {
+                            textRetryCount++;
+                            debugLog(`SubAgent [${this.taskId}]: Model returned text without executing tools. Rejecting and enforcing tool execution (attempt ${textRetryCount}/${MAX_TEXT_RETRIES}).`);
+                            const forcePrompt = `[SYSTEM DIRECTIVE (CRITICAL)]: You are an autonomous execution sub-agent. You have returned text without executing any tools or making code changes. You MUST call tools (e.g. 'read_file', 'modify_file', 'write_file', 'grep_search', 'run_command', or 'run_debug_script') to implement your assigned task objective: "${this.intent}". Do NOT just describe your plan in text—execute the changes using your tools now.`;
+                            this.pingHeartbeat();
+                            turnResult = await this.chat.sendMessage(forcePrompt, undefined, signal);
+                            this.updateUsage(turnResult);
+                            continue;
+                        }
                         success = true;
                         finalSummary = turnResult.response.text() || 'Task completed without text summary.';
                         break;
                     }
+                    hasExecutedAnyTool = true;
+                    // Once tools have been called, switch to AUTO mode so the agent can provide a text summary on completion
+                    this.chat.setToolConfig(undefined);
                     const toolResponses = [];
                     // Execute all requested tools sequentially (to avoid parallel lock contention from the same agent)
                     for (const call of calls) {
@@ -273,7 +294,7 @@ export class SubAgentRunner {
                         debugLog(`SubAgent [${this.taskId}]: Executing tool ${call.name}`);
                         let responseData;
                         try {
-                            responseData = await executeScopedTool(call.name, call.args, this.workspaceRoot, this.taskId, this.bus, this.locks, this.pingHeartbeat, undefined, this.taskScope);
+                            responseData = await executeScopedTool(call.name, call.args, this.workspaceRoot, this.taskId, this.bus, this.locks, this.pingHeartbeat, undefined, this.taskScope, this.readCache);
                         }
                         catch (err) {
                             responseData = { error: err.message || String(err) };
@@ -365,6 +386,7 @@ export class SubAgentRunner {
             `   - Step 3 (Verify): Use 'run_debug_script', 'run_fuzz_probe', 'check_heap_delta', 'check_behavioral_drift', or 'run_command' to test your changes if necessary.\n` +
             `   - Step 4 (Conclude): Once your specific objective is fully met, stop calling tools and return a text summary of your changes.\n` +
             `4. Coordinate: Use 'read_messages' to check for updates from other agents. Use 'post_message' if you discover breaking changes affecting others.\n` +
+            `5. IMMEDIATE TOOL ACTION (CRITICAL): On your very first turn, you MUST call tools to inspect or modify code. Do NOT output a conversational text plan or description on Turn 1—call the required tools directly.\n` +
             `</critical_guidelines>`);
     }
     /**

package/dist/utils/localSyntaxValidator.d.ts

@@ -1,9 +1,36 @@
 /**
- * Performs fast, local syntax validation using bracket-matching state machine and native parsers.
- * Acts as a first-pass filter before AI-based validation.
+ * Represents the structured result of a local syntax validation check.
  */
 export interface ValidationResult {
+    /**
+     * Indicates whether the validated source code is syntactically valid without detected defects,
+     * unclosed delimiters, or AI-generated truncation markers.
+     */
     isValid: boolean;
+    /**
+     * A detailed, human-readable error description explaining why syntax validation failed,
+     * frequently including the character offset or delimiter mismatch information.
+     */
     error?: string;
 }
+/**
+ * Performs fast, deterministic local syntax validation on source code using native parsers,
+ * AI truncation heuristics, and a single-pass lexical bracket-matching state machine.
+ *
+ * ### Validation Lifecycle:
+ * 1. **Native JSON Verification**: Validates `.json` files via `JSON.parse` with exact error reporting.
+ * 2. **AI Truncation Detection**: Flags incomplete edits containing ellipsis placeholder comments via {@link isTruncated}.
+ * 3. **Dialect Classification**: Categorizes files into C-style, Hash-style, or JS/TS dialects, allowing unrecognized formats to pass through.
+ * 4. **Single-Pass Lexical Scanning ($O(N)$)**:
+ *    - Ignores single-line (`//`, `#`) and multi-line (`/* ... *\/`) comments.
+ *    - Skips string literals (`'...'`, `"..."`) while handling escape sequences (`\`).
+ *    - Tracks JS/TS template literals (`` `...` ``) and nested interpolation expressions (`${...}`).
+ *    - Disambiguates JS/TS regular expressions (`/.../flags`) from division operators (`/`) using token lookback.
+ *    - Maintains a delimiter stack for `{}`, `[]`, `()`, and `${}` with positional error reporting on mismatches.
+ * 5. **Terminal State Verification**: Confirms all brackets, comments, strings, template literals, and regexes are properly closed.
+ *
+ * @param filePath - The file path used to identify file extension and language-specific syntax rules.
+ * @param content - The raw text content of the file to validate.
+ * @returns A {@link ValidationResult} object indicating whether validation passed or detailing the failure reason.
+ */
 export declare function localValidate(filePath: string, content: string): ValidationResult;

package/dist/utils/localSyntaxValidator.js

@@ -1,6 +1,15 @@
 import path from 'path';
 /**
- * Checks if file content contains placeholder comments indicating AI code truncation.
+ * Inspects source file content for comment markers that indicate AI code generation truncation
+ * (e.g., `// ... existing code ...`, `/* ... rest of implementation ... *\/`, or `// ... remaining ...`).
+ *
+ * Large language models often insert placeholder comments to abbreviate long files when generating edits.
+ * Applying truncated content directly to disk would destroy existing code; this heuristic flags such
+ * content so it can be rejected or regenerated prior to mutation.
+ *
+ * @internal
+ * @param content - The raw source file content string to inspect.
+ * @returns `true` if any line matches known truncation placeholder patterns; `false` otherwise.
  */
 function isTruncated(content) {
     const lines = content.split('\n');
@@ -16,6 +25,122 @@ function isTruncated(content) {
     }
     return false;
 }
+/**
+ * File extensions that follow C-style syntax conventions, including `//` single-line comments,
+ * `/* ... *\/` block comments, and standard `{`, `[`, `(` bracket nesting rules.
+ */
+const C_STYLE_EXTS = new Set([
+    '.ts',
+    '.js',
+    '.tsx',
+    '.jsx',
+    '.css',
+    '.html',
+    '.rs',
+    '.go',
+    '.java',
+    '.cpp',
+    '.c',
+    '.h',
+    '.cs',
+    '.php',
+    '.swift',
+]);
+/**
+ * File extensions for scripting and configuration languages that utilize `#` for single-line comments.
+ */
+const HASH_STYLE_EXTS = new Set(['.py', '.rb', '.sh', '.yaml', '.yml']);
+/**
+ * File extensions for JavaScript and TypeScript dialects requiring specialized parsing
+ * for template literals (`` `...` ``) and regular expression literals (`/.../`).
+ */
+const JS_TS_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+/**
+ * JavaScript/TypeScript keywords that can immediately precede an expression context.
+ * When a forward slash `/` follows one of these keywords, it is parsed as a regular expression literal
+ * rather than an arithmetic division operator.
+ */
+const EXPR_KEYWORDS = new Set([
+    'return',
+    'case',
+    'typeof',
+    'void',
+    'delete',
+    'yield',
+    'await',
+    'throw',
+    'instanceof',
+    'in',
+    'of',
+    'new',
+    'else',
+    'do',
+    'tok',
+]);
+/**
+ * Punctuation characters and operators that denote an expression context in JavaScript/TypeScript.
+ * When a forward slash `/` follows one of these tokens, it initiates a regular expression literal.
+ */
+const EXPR_PUNCT = new Set([
+    '(',
+    '[',
+    '{',
+    ';',
+    ',',
+    '=',
+    '+',
+    '-',
+    '*',
+    '%',
+    '&',
+    '|',
+    '^',
+    '!',
+    '~',
+    '?',
+    ':',
+    '<',
+    '/',
+    '=>',
+    '${',
+]);
+/**
+ * Regular expression matching word characters valid in JavaScript/TypeScript identifiers.
+ */
+const wordCharRegex = new RegExp('[a-zA-Z0-9_$]');
+/**
+ * Regular expression matching alphabetic characters representing regex flags (e.g., `g`, `i`, `m`, `s`, `u`, `y`, `v`).
+ */
+const alphaRegex = new RegExp('[a-zA-Z]');
+/**
+ * Mapping of opening delimiter tokens to their expected closing delimiter counterparts.
+ */
+const BRACKET_PAIRS = {
+    '{': '}',
+    '[': ']',
+    '(': ')',
+    '${': '}',
+};
+/**
+ * Performs fast, deterministic local syntax validation on source code using native parsers,
+ * AI truncation heuristics, and a single-pass lexical bracket-matching state machine.
+ *
+ * ### Validation Lifecycle:
+ * 1. **Native JSON Verification**: Validates `.json` files via `JSON.parse` with exact error reporting.
+ * 2. **AI Truncation Detection**: Flags incomplete edits containing ellipsis placeholder comments via {@link isTruncated}.
+ * 3. **Dialect Classification**: Categorizes files into C-style, Hash-style, or JS/TS dialects, allowing unrecognized formats to pass through.
+ * 4. **Single-Pass Lexical Scanning ($O(N)$)**:
+ *    - Ignores single-line (`//`, `#`) and multi-line (`/* ... *\/`) comments.
+ *    - Skips string literals (`'...'`, `"..."`) while handling escape sequences (`\`).
+ *    - Tracks JS/TS template literals (`` `...` ``) and nested interpolation expressions (`${...}`).
+ *    - Disambiguates JS/TS regular expressions (`/.../flags`) from division operators (`/`) using token lookback.
+ *    - Maintains a delimiter stack for `{}`, `[]`, `()`, and `${}` with positional error reporting on mismatches.
+ * 5. **Terminal State Verification**: Confirms all brackets, comments, strings, template literals, and regexes are properly closed.
+ *
+ * @param filePath - The file path used to identify file extension and language-specific syntax rules.
+ * @param content - The raw text content of the file to validate.
+ * @returns A {@link ValidationResult} object indicating whether validation passed or detailing the failure reason.
+ */
 export function localValidate(filePath, content) {
     const ext = path.extname(filePath).toLowerCase();
     // 1. Check JSON files using native JSON parser
@@ -31,44 +156,23 @@ export function localValidate(filePath, content) {
             };
         }
     }
-    // 2. Check for truncation markers
+    // 2. Check for truncation markers (AI placeholder comments)
     if (isTruncated(content)) {
         return {
             isValid: false,
             error: 'File appears to be truncated (contains placeholder comments)',
         };
     }
-    const C_STYLE_EXTS = [
-        '.ts',
-        '.js',
-        '.tsx',
-        '.jsx',
-        '.css',
-        '.html',
-        '.rs',
-        '.go',
-        '.java',
-        '.cpp',
-        '.c',
-        '.h',
-        '.cs',
-        '.php',
-        '.swift',
-    ];
-    const HASH_STYLE_EXTS = ['.py', '.rb', '.sh', '.yaml', '.yml'];
-    const isJsTs = ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext);
-    const isCStyle = C_STYLE_EXTS.includes(ext);
-    const isHashStyle = HASH_STYLE_EXTS.includes(ext);
+    const isJsTs = JS_TS_EXTS.has(ext);
+    const isCStyle = C_STYLE_EXTS.has(ext);
+    const isHashStyle = HASH_STYLE_EXTS.has(ext);
+    // Pass-through for unrecognized or un-parsed file formats (e.g., plain text, markdown)
     if (!isCStyle && !isHashStyle && !isJsTs) {
         return { isValid: true };
     }
+    // Delimiter tracking stack storing expected open delimiters ('{', '[', '(', '${')
     const stack = [];
-    const pairs = {
-        '{': '}',
-        '[': ']',
-        '(': ')',
-        '${': '}',
-    };
+    // Lexical scanner state flags
     let inSingleComment = false;
     let inMultiComment = false;
     let inString = false;
@@ -76,51 +180,9 @@ export function localValidate(filePath, content) {
     let inTemplate = false;
     let inRegex = false;
     let inRegexCharClass = false;
-    // Track tokens to determine if '/' can start a regex literal
+    // Track preceding tokens to determine if '/' represents a regex literal or division operator
     let lastToken = '';
     let currentWord = '';
-    const EXPR_KEYWORDS = new Set([
-        'return',
-        'case',
-        'typeof',
-        'void',
-        'delete',
-        'yield',
-        'await',
-        'throw',
-        'instanceof',
-        'in',
-        'of',
-        'new',
-        'else',
-        'do',
-        'tok',
-    ]);
-    const EXPR_PUNCT = new Set([
-        '(',
-        '[',
-        '{',
-        ';',
-        ',',
-        '=',
-        '+',
-        '-',
-        '*',
-        '%',
-        '&',
-        '|',
-        '^',
-        '!',
-        '~',
-        '?',
-        ':',
-        '<',
-        '/',
-        '=>',
-        '${',
-    ]);
-    const wordCharRegex = new RegExp('[a-zA-Z0-9_$]');
-    const alphaRegex = new RegExp('[a-zA-Z]');
     for (let i = 0; i < content.length; i++) {
         const char = content[i];
         const nextChar = content[i + 1];
@@ -142,7 +204,7 @@ export function localValidate(filePath, content) {
         // --- 3. STRING LITERAL ('...' or "...") ---
         if (inString) {
             if (char === '\\') {
-                i++; // skip escaped char
+                i++; // skip escaped character
                 continue;
             }
             if (char === stringChar) {
@@ -154,11 +216,11 @@ export function localValidate(filePath, content) {
         // --- 4. TEMPLATE LITERAL (`...`) ---
         if (inTemplate) {
             if (char === '\\') {
-                i++; // skip escaped char
+                i++; // skip escaped character
                 continue;
             }
             if (char === '$' && nextChar === '{') {
-                // Enter template expression ${...}
+                // Enter template interpolation expression ${...}
                 stack.push('${');
                 inTemplate = false;
                 i++; // skip '{'
@@ -174,20 +236,22 @@ export function localValidate(filePath, content) {
         // --- 5. REGEX LITERAL (/.../) ---
         if (inRegex) {
             if (char === '\\') {
-                i++; // skip escaped char
+                i++; // skip escaped regex character
                 continue;
             }
             if (char === '[') {
+                // Enter regex character class [...] where '/' does not terminate the regex
                 inRegexCharClass = true;
                 continue;
             }
             if (char === ']') {
+                // Exit regex character class
                 inRegexCharClass = false;
                 continue;
             }
             if (char === '/' && !inRegexCharClass) {
                 inRegex = false;
-                // Skip regex flags (e.g. /foo/gim)
+                // Skip trailing regex flags (e.g. /foo/gimsu)
                 while (i + 1 < content.length && alphaRegex.test(content[i + 1])) {
                     i++;
                 }
@@ -260,6 +324,7 @@ export function localValidate(filePath, content) {
         }
         // --- 7. BRACKET MATCHING ---
         if (['{', '[', '('].includes(char)) {
+            // For hash-style languages (Python/YAML), skip curly braces to avoid false positives with dictionary/block formatting
             if (isHashStyle && char === '{')
                 continue;
             stack.push(char);
@@ -268,7 +333,7 @@ export function localValidate(filePath, content) {
             if (isHashStyle && char === '}')
                 continue;
             const last = stack.pop();
-            if (!last || pairs[last] !== char) {
+            if (!last || BRACKET_PAIRS[last] !== char) {
                 return {
                     isValid: false,
                     error: "Unbalanced character '" + char + "' at position " + i,