@gitsense/gsc-utils 0.1.0

package/src/GSToolBlockUtils.js

@@ -0,0 +1,108 @@
+/**
+ * Component: GitSense Tool Block Utilities
+ * Block-UUID: 72db6a5f-3b09-49e8-8f39-d4e3d37b510a
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions for identifying and parsing GitSense Chat Tool Blocks.
+ * Language: JavaScript
+ * Created-at: 2025-04-27T01:29:53.576Z
+ * Authors: Gemini 2.5 Pro (v1.0.0)
+ */
+
+
+/**
+ * Checks if a given code block content represents a GitSense Chat Tool Block.
+ * It verifies if the first non-empty line starts with "# GitSense Chat Tool".
+ *
+ * @param {string} content - The raw content of the code block (within the fences).
+ * @returns {boolean} True if it's a GitSense Chat Tool Block, false otherwise.
+ */
+function isToolBlock(content) {
+    if (!content || typeof content !== 'string') {
+        return false;
+    }
+
+    if (content.match(/^\s*# GitSense Chat Tool\n\s*{/)) 
+        return true;
+
+    return false;
+}
+
+/**
+ * Parses the content of a GitSense Chat Tool Block to extract the JSON payload.
+ * It strips the marker line and any subsequent lines starting with '#' (comments)
+ * or empty lines before attempting to parse the remaining content as JSON.
+ *
+ * @param {string} content - The raw content of the code block, verified by isToolBlock.
+ * @returns {{ tool: string, config: object, data: object } | null} The parsed JSON object { tool, config, data } or null if parsing fails or format is invalid.
+ * @throws {Error} If JSON parsing fails.
+ */
+function parseToolBlock(content) {
+    if (!isToolBlock(content)) {
+        return null; // Should already be verified, but double-check
+    }
+
+    const lines = content.split('\n');
+    const jsonLines = [];
+    let markerFound = false;
+
+    for (const line of lines) {
+        const trimmedLine = line.trim();
+
+        if (!markerFound) {
+            if (trimmedLine.startsWith('# GitSense Chat Tool')) {
+                markerFound = true; // Skip the marker line itself
+            }
+            continue; // Skip lines before the marker (shouldn't be any non-empty ones based on isToolBlock)
+        }
+
+        // After the marker, skip empty lines and comment lines
+        if (trimmedLine.length === 0 || /^\s*#/.test(line)) {
+            continue;
+        }
+
+        // Keep lines that are part of the JSON
+        jsonLines.push(line);
+    }
+
+    const jsonString = jsonLines.join('\n');
+
+    if (!jsonString) {
+        // No JSON content found after stripping comments/marker
+        throw new Error("No JSON content found in the tool block after stripping marker and comments.");
+    }
+
+    try {
+        const parsed = JSON.parse(jsonString);
+
+        // Basic validation of the parsed structure
+        // The properties tool and  config are required.  Tool cannot be null or undefined but
+        // config can't. The reason for requiring config to be declared is to reserve the 
+        // property name.
+        if (typeof parsed !== 'object' || parsed === null) {
+            throw new Error("Parsed content is not a valid JSON object.");
+        }
+        if (typeof parsed.tool !== 'string' || !parsed.tool) {
+            throw new Error("Parsed JSON object is missing the required 'tool' string property.");
+        }
+
+        if (typeof parsed.config === 'undefined') {
+            throw new Error("Parsed JSON object is missing the required 'config' property.");
+        }
+
+        return parsed;
+    } catch (error) {
+        // Re-throw JSON parsing errors with more context
+        throw new Error(`Failed to parse tool block JSON: ${error.message}\nContent after stripping comments:\n${jsonString}`);
+    }
+}
+
+function formatToolBlock(toolData) {
+    return `# GitSense Chat Tool\n\n${JSON.stringify(toolData, null, 2)}`;
+}
+
+module.exports = {
+    isToolBlock,
+    parseToolBlock,
+    formatToolBlock
+}

package/src/GitSenseChatUtils.js

@@ -0,0 +1,386 @@
+/**
+ * Component: GitSenseChatUtils
+ * Block-UUID: 5e8d1a9c-0b3f-4e1a-8c7d-9f0b2e1d3a4b
+ * Parent-UUID: 7a9b1c8e-f1a4-4b2d-9e8f-6f7a0b1c2d3f
+ * Version: 2.1.1
+ * Description: Interface class for GitSense Chat utilities providing a unified API for code block parsing (markdown), extraction, and patch operations. Integrates functionalities from CodeBlockUtils and PatchUtils modules.
+ * Language: JavaScript
+ * Created-at: 2025-04-15T16:04:26.780Z
+ * Authors: Claude 3.7 Sonnet (v1.0.0), Gemini 2.5 Pro (v2.0.0), Gemini 2.5 Pro (v2.1.0), Gemini 2.5 Pro (v2.1.1)
+ */
+
+
+const ChatUtils = require('./ChatUtils');
+const CodeBlockUtils = require('./CodeBlockUtils');
+const ContextUtils = require('./ContextUtils');
+const MessageUtils = require('./MessageUtils');
+const AnalysisBlockUtils = require('./AnalysisBlockUtils');
+const PatchUtils = require('./PatchUtils');
+const GSToolBlockUtils = require('./GSToolBlockUtils');
+const LLMUtils = require('./LLMUtils');
+const JsonUtils = require('./JsonUtils');
+
+const {
+    estimateTokens
+} = LLMUtils;
+
+const { 
+    detectJsonComments 
+} = JsonUtils;
+
+const {
+    isOverviewBuilderChat,
+    getChatMessages,
+} = ChatUtils;
+
+const {
+    getChatTemplateMessages,
+    getMessagesBeforeId,
+    getMessageById,
+    getLastMessage,
+    findMessages,
+    deleteMessagesByIds,
+    getMessageContentType,
+    isContextMessage,
+    isContextItemsOverviewMessage
+} = MessageUtils;
+
+const {
+    isOverviewBlock,
+    getOverviewType,
+    parseOverviewMetadata,
+    validateOverviewMetadata,
+} = AnalysisBlockUtils;
+
+const {
+    COMMENT_STYLES,
+    generateUUID,
+    validateUUID,
+    isValidISOTimestamp,
+    parseHeader,
+    findAllCodeFences,
+    matchFencesAndExtractBlocks,
+    processCodeBlocks,
+    extractCodeBlocks,
+    fixTextCodeBlocks,
+    containsPatch,
+    detectCodeBlockRelationships,
+    detectIncompleteCodeBlock,
+    extractFilePaths,
+    extractContinuationInfo,
+    formatWithLineNumbers,
+    formatBlocksWithLineNumbers,
+    formatBlockWithLineNumbers,
+    removeLineNumbers,
+    generateContinuationPrompt,
+    parseCommentDelimitedBlocks,
+    removeCodeBlockMarkers,
+    updateCodeBlockByIndex,
+    deleteCodeBlockByIndex,
+} = CodeBlockUtils;
+
+const {
+    isPatchBlock,
+    determinePatchFormat,
+    extractPatchMetadata,
+    validatePatchMetadata,
+    extractPatchContent,
+    extractContextPatches,
+    convertContextPatchToDiff,
+    convertDiffToContextPatch,
+    verifyAndCorrectLineNumbers,
+} = PatchUtils;
+
+const { 
+    isToolBlock,
+    parseToolBlock
+} = GSToolBlockUtils;
+
+/**
+ * GitSenseChatUtils class provides a unified interface to code block and patch utilities.
+ * Focuses on markdown code block extraction and processing.
+ */
+class GitSenseChatUtils {
+    /**
+     * Create a new GitSenseChatUtils instance
+     * @param {Object} options - Configuration options
+     * @param {boolean} [options.silent=false] - Whether to suppress console warning messages
+     */
+    constructor(options = {}) {
+        this.options = {
+            silent: false,
+            ...options
+        };
+
+        // Make comment styles available as a property via CodeBlockUtils
+        this.commentStyles = CodeBlockUtils.COMMENT_STYLES;
+    }
+
+    /**
+     * Parse markdown code blocks from input text using the primary extractor.
+     * @param {string} input - The input text containing markdown code blocks.
+     * @param {Object} [options] - Options for extraction (overrides instance options).
+     * @returns {Object} Object containing extracted blocks and warnings { blocks: Array, warnings: Array }.
+     */
+    parseCodeBlocks(input, options) {
+        // Wraps the primary markdown block extractor for consistency
+        return CodeBlockUtils.extractCodeBlocks(input, options || this.options);
+    }
+
+    /**
+     * Remove custom code block start/complete markers from markdown text.
+     * @param {string} markdownText - The markdown text containing code blocks with markers.
+     * @returns {string} The markdown text with code block markers removed.
+     */
+    removeCodeBlockMarkers(markdownText) {
+        // Uses function from CodeBlockUtils
+        return CodeBlockUtils.removeCodeBlockMarkers(markdownText);
+    }
+
+    /**
+     * Extract markdown code blocks from text (simple API).
+     * @param {string} text - The input text containing markdown code blocks.
+     * @param {Object} [options] - Options for extraction (overrides instance options).
+     * @returns {Object} Object containing extracted blocks and warnings { blocks: Array, warnings: Array }.
+     */
+    extractCodeBlocks(text, options) {
+        // Uses function from CodeBlockUtils
+        return CodeBlockUtils.extractCodeBlocks(text, options || this.options);
+    }
+
+    /**
+     * Process text with markdown code blocks, returning detailed information including incomplete status.
+     * @param {string} text - The input text containing markdown code blocks.
+     * @param {Object} [options] - Options for processing (overrides instance options).
+     * @returns {Object} Processed blocks, warnings, and incomplete status info.
+     */
+    processCodeBlocks(text, options) {
+        // Uses function from CodeBlockUtils
+        return CodeBlockUtils.processCodeBlocks(text, options || this.options);
+    }
+
+    /**
+     * Extract only patch blocks from text.
+     * @param {string} text - The input text potentially containing patch blocks.
+     * @param {Object} [options] - Options for processing (overrides instance options).
+     * @returns {Object} Object containing extracted patch blocks and warnings { blocks: Array, warnings: Array }.
+     */
+    extractPatchBlocks(text, options) {
+        const { blocks, warnings } = CodeBlockUtils.processCodeBlocks(text, options || this.options);
+        const patchBlocks = blocks.filter(block => block.type === 'patch');
+        // Filter warnings? For now, return all warnings encountered during processing.
+        return { blocks: patchBlocks, warnings: warnings };
+    }
+
+    /**
+     * Fix invalid UUIDs in code blocks (markdown headers or patch metadata) within text.
+     * @param {string} text - The input text containing code blocks.
+     * @returns {Object} Object containing fixed text and whether changes were made { text: string, modified: boolean }.
+     */
+    fixTextCodeBlocks(text) {
+        // Uses function from CodeBlockUtils
+        return CodeBlockUtils.fixTextCodeBlocks(text);
+    }
+
+    /**
+     * Determines if a code block's content represents a patch.
+     * @param {string} codeBlockContent - The content of the code block (between the fences).
+     * @returns {boolean} True if the code block is a patch.
+     */
+    isPatchBlock(codeBlockContent) {
+        // Uses function from PatchUtils
+        return PatchUtils.isPatchBlock(codeBlockContent);
+    }
+
+    /**
+     * Determines the type of patch format used (e.g., 'context', 'diff').
+     * @param {string} patchText - The patch text content.
+     * @returns {string} 'context', 'diff', or 'unknown'.
+     */
+    determinePatchFormat(patchText) {
+        // Uses function from PatchUtils
+        return PatchUtils.determinePatchFormat(patchText);
+    }
+
+    /**
+     * Extracts metadata from a patch block.
+     * @param {string} patchText - The patch text including metadata.
+     * @returns {Object} Extracted metadata object.
+     */
+    extractPatchMetadata(patchText) {
+        // Uses function from PatchUtils
+        return PatchUtils.extractPatchMetadata(patchText);
+    }
+
+    /**
+     * Validates patch metadata for required fields and format.
+     * @param {Object} metadata - The patch metadata object.
+     * @returns {Object} Validation result { valid: boolean, errors: Array }.
+     */
+    validatePatchMetadata(metadata) {
+        // Uses function from PatchUtils
+        return PatchUtils.validatePatchMetadata(metadata);
+    }
+
+    /**
+     * Extracts context-based patch sections (@@ ... @@) from patch text.
+     * @param {string} patchText - The full patch text content.
+     * @returns {Array|null} Array of context patch objects or null if invalid format.
+     */
+    extractContextPatches(patchText) {
+        // Uses function from PatchUtils
+        return PatchUtils.extractContextPatches(patchText);
+    }
+
+    /**
+     * Extracts the diff content (lines after metadata) from a patch block.
+     * @param {string} patchText - The full patch text content.
+     * @returns {string} The diff content only.
+     */
+    extractDiffContent(patchText) {
+        // Uses function from PatchUtils (assuming it's named extractPatchContent or similar)
+        // If PatchUtils.extractDiffContent exists, use it. Otherwise, use extractPatchContent.
+        return PatchUtils.extractDiffContent 
+            ? PatchUtils.extractDiffContent(patchText) 
+            : PatchUtils.extractPatchContent(patchText);
+    }
+
+    /**
+     * Converts a context-based patch representation to a traditional diff patch string.
+     * (Requires external 'diff' library functionality, likely within PatchUtils).
+     * @param {Array} contextPatches - Array of context patch objects.
+     * @param {string} sourceCode - The source code to patch.
+     * @returns {string} Traditional diff patch content.
+     */
+    convertContextPatchToDiff(contextPatches, sourceCode) {
+        // Uses function from PatchUtils
+        return PatchUtils.convertContextPatchToDiff(contextPatches, sourceCode);
+    }
+
+    /**
+     * Converts a traditional diff patch string to a context-based patch representation.
+     * (Requires external 'diff' library functionality, likely within PatchUtils).
+     * @param {string} diffContent - Traditional diff content.
+     * @param {string} sourceCode - The source code the diff applies to.
+     * @returns {Array} Array of context patch objects.
+     */
+    convertDiffToContextPatch(diffContent, sourceCode) {
+        // Uses function from PatchUtils
+        return PatchUtils.convertDiffToContextPatch(diffContent, sourceCode);
+    }
+
+    /**
+     * Generates a valid RFC 4122 UUID v4.
+     * @returns {string} A valid UUID v4.
+     */
+    generateUUID() {
+        // Uses function from CodeBlockUtils
+        return CodeBlockUtils.generateUUID();
+    }
+
+    /**
+     * Validates a UUID string.
+     * @param {string} uuid - The UUID string to validate.
+     * @returns {Object} Object containing validation results.
+     */
+    validateUUID(uuid) {
+        // Uses function from CodeBlockUtils
+        return CodeBlockUtils.validateUUID(uuid);
+    }
+
+    /**
+     * Validates if a string is a valid ISO 8601 timestamp.
+     * @param {string} timestamp - The timestamp to validate.
+     * @returns {boolean} - True if valid, false otherwise.
+     */
+    isValidISOTimestamp(timestamp) {
+        // Uses function from CodeBlockUtils
+        return CodeBlockUtils.isValidISOTimestamp(timestamp);
+    }
+}
+
+// Export the main class, the aggregated CodeBlockUtils, PatchUtils,
+// and individual functions for backward compatibility or direct use.
+module.exports = {
+    // Main class
+    GitSenseChatUtils,
+
+    // Aggregated Modules
+    CodeBlockUtils,
+    ContextUtils,
+    MessageUtils,
+    PatchUtils,
+    LLMUtils,
+    AnalysisBlockUtils,
+    ChatUtils,
+    GSToolBlockUtils,
+    JsonUtils,
+
+    // --- Individual Function Exports (sourced correctly) ---
+
+    // Code Block Processing (from CodeBlockUtils)
+    COMMENT_STYLES,
+    extractCodeBlocks,
+    processCodeBlocks,
+    fixTextCodeBlocks,
+    parseHeader,
+
+    // UUID (from CodeBlockUtils)
+    generateUUID,
+    validateUUID,
+
+    // Timestamp (from CodeBlockUtils)
+    isValidISOTimestamp,
+
+    // Patch Detection/Integration (from CodeBlockUtils)
+    containsPatch,
+
+    // Relationships / Incomplete Blocks (from CodeBlockUtils)
+    detectCodeBlockRelationships,
+    detectIncompleteCodeBlock,
+    extractFilePaths,
+    extractContinuationInfo,
+    generateContinuationPrompt,
+
+    // Line formatter (from CodeBlockUtils)
+    formatWithLineNumbers,
+    formatBlockWithLineNumbers,
+    formatBlocksWithLineNumbers,
+    removeLineNumbers,
+     
+    // Other Utilities (from CodeBlockUtils)
+    removeCodeBlockMarkers,
+    parseCommentDelimitedBlocks,
+    updateCodeBlockByIndex,
+    deleteCodeBlockByIndex,
+
+    // Analysis Block Utilities 
+    isOverviewBlock,
+    getOverviewType,
+    parseOverviewMetadata,
+    validateOverviewMetadata,
+
+    // ChatUtils
+    getChatMessages, 
+
+    // Message Utils
+    getChatTemplateMessages,
+    getMessagesBeforeId,
+    getMessageById,
+    getLastMessage,
+    findMessages,
+    deleteMessagesByIds,
+    getMessageContentType,
+    isContextMessage,
+    isContextItemsOverviewMessage,
+
+    // LLM Utils
+    estimateTokens,
+
+    // GS Tool Block
+    isToolBlock,
+    parseToolBlock,
+
+    // Note: Internal helpers like findAllCodeFences, matchFencesAndExtractBlocks are
+    // typically not exported directly from the facade but are available via CodeBlockUtils object.
+};

package/src/JsonUtils.js

@@ -0,0 +1,101 @@
+/**
+ * Component: JSON Utils
+ * Block-UUID: 751cb03b-731d-4fa1-9dc0-5d4142275f20
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: JSON Utilities
+ * Language: javascript
+ * Created-at: 2025-05-24T01:15:44.320Z
+ * Authors: Gemini 2.5 Flash Thinking (v1.0.0)
+ */
+
+
+/**
+ * Detects C-style block (/* ... *\/) and single-line (// ...) comments
+ * within a string, correctly ignoring comments that appear inside
+ * JSON string literals.
+ *
+ * @param {string} jsonString The string potentially containing JSON and comments.
+ * @returns {string[]} An array of detected comment strings (including their markers).
+ */
+function detectJsonComments(jsonString) {
+    const comments = [];
+    let inString = false;
+    let inBlockComment = false;
+    let inLineComment = false;
+    let commentStartIndex = -1;
+
+    for (let i = 0; i < jsonString.length; i++) {
+        const char = jsonString[i];
+        const nextChar = jsonString[i + 1];
+
+        // Handle escape sequences within strings
+        if (inString && char === '\\') {
+            i++; // Skip the next character as it's escaped
+            continue;
+        }
+
+        // Handle entering/exiting strings
+        if (char === '"' && !inBlockComment && !inLineComment) {
+            inString = !inString;
+            continue; // Move to the next character
+        }
+
+        // If currently in a block comment
+        if (inBlockComment) {
+            if (char === '*' && nextChar === '/') {
+                // End of block comment found
+                comments.push(jsonString.substring(commentStartIndex, i + 2));
+                inBlockComment = false;
+                commentStartIndex = -1;
+                i++; // Skip the '/' character
+                continue;
+            }
+            // Continue consuming characters within the comment
+            continue;
+        }
+
+        // If currently in a line comment
+        if (inLineComment) {
+            if (char === '\n' || i === jsonString.length - 1) {
+                // End of line comment found (newline or end of string)
+                comments.push(jsonString.substring(commentStartIndex, i + (char === '\n' ? 0 : 1)));
+                inLineComment = false;
+                commentStartIndex = -1;
+                // Do not continue, let the loop handle the newline or end of string
+            }
+            // Continue consuming characters within the comment
+            continue;
+        }
+
+        // If not in a string or comment, check for comment starts
+        if (!inString) {
+            // Check for block comment start
+            if (char === '/' && nextChar === '*') {
+                inBlockComment = true;
+                commentStartIndex = i;
+                i++; // Skip the '*' character
+                continue;
+            }
+
+            // Check for single-line comment start
+            if (char === '/' && nextChar === '/') {
+                inLineComment = true;
+                commentStartIndex = i;
+                i++; // Skip the '/' character
+                continue;
+            }
+        }
+    }
+
+    // Handle case where a line comment is the very last thing in the string
+    if (inLineComment && commentStartIndex !== -1) {
+         comments.push(jsonString.substring(commentStartIndex));
+    }
+
+    return comments;
+}
+
+module.exports = {
+    detectJsonComments
+};

package/src/LLMUtils.js

@@ -0,0 +1,31 @@
+/**
+ * Component: LLMUtils
+ * Block-UUID: a3106054-42f1-474f-96f3-182d66eb19a0
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions related to Large Language Model interactions, such as token estimation.
+ * Language: JavaScript
+ * Created-at: 2025-04-22T17:16:00.590Z
+ * Authors: Gemini 2.5 Pro (v1.0.0)
+ */
+
+
+/**
+ * Estimates the number of tokens in a given text string.
+ * This is a basic estimation using the common heuristic of ~4 characters per token.
+ * Actual token count can vary significantly based on the specific tokenizer used by an LLM.
+ *
+ * @param {string} text - The text to estimate tokens for.
+ * @returns {number} An estimated token count. Returns 0 if input is not a non-empty string.
+ */
+function estimateTokens(text) {
+    if (typeof text !== 'string' || text.length === 0) {
+        return 0;
+    }
+    // Basic heuristic: average token length is around 4 characters
+    return Math.ceil(text.length / 4);
+}
+
+module.exports = {
+    estimateTokens,
+};