@gitsense/gsc-utils 0.1.0

package/src/CodeBlockUtils/updateCodeBlock.js

@@ -0,0 +1,372 @@
+/**
+ * Component: CodeBlockUtils Update Code Block
+ * Block-UUID: 6a7b8c9d-0e1f-42a3-b4c5-d6e7f8a9b0c1
+ * Parent-UUID: 5f9c1e3a-7b2d-4e8f-a1d0-9c4b2e1f8a0b
+ * Version: 1.4.0
+ * Description: Provides functions to update the content of a specific code block within a string, identified by index, UUID, or direct reference.
+ * Language: JavaScript
+ * Created-at: 2025-04-16T00:56:57.352Z
+ * Authors: Gemini 2.5 Pro (v1.0.0), Gemini 2.5 Pro (v1.1.0), Gemini 2.5 Pro (v1.2.0), Gemini 2.5 Pro (v1.3.0), Gemini 2.5 Flash Thinking (v1.4.0)
+ */
+
+
+// Dependencies from other modules within CodeBlockUtils
+const { findAllCodeFences, matchFencesAndExtractBlocks, findCodeBlockByUUID } = require('./blockExtractor'); // Added findCodeBlockByUUID
+const { processCodeBlocks } = require('./blockProcessor'); // To get parsed block info
+
+/**
+ * Replaces the content of a code block specified by its index within a message string.
+ *
+ * @param {string} messageContent - The original message string containing code blocks.
+ * @param {number} blockIndex - The 0-based index of the code block to replace.
+ * @param {string} newCodeContent - The new raw content (code, potentially including header) to insert into the block.
+ * @param {string} [language] - Optional: The language identifier for the updated code block fence. If omitted, the original language is preserved.
+ * @returns {string} The message content with the specified code block updated.
+ * @throws {Error} If the blockIndex is out of bounds or if block boundaries cannot be determined.
+ */
+function updateCodeBlockByIndex(messageContent, blockIndex, newCodeContent, language = undefined) {
+    if (typeof messageContent !== 'string') {
+        throw new Error("messageContent must be a string.");
+    }
+    if (typeof blockIndex !== 'number' || blockIndex < 0) {
+        throw new Error("blockIndex must be a non-negative number.");
+    }
+    if (typeof newCodeContent !== 'string') {
+        // Allow empty string replacement, but not other types
+        throw new Error("newCodeContent must be a string.");
+    }
+
+    // Step 1: Find all fence positions to get accurate start/end of the full block
+    const { openingPositions, closingPositions } = findAllCodeFences(messageContent);
+    const { completeBlocks, incompleteBlocks, warnings: extractorWarnings } = matchFencesAndExtractBlocks(
+        messageContent, openingPositions, closingPositions
+    );
+
+    // Combine complete and incomplete for indexing, assuming we might want to update an incomplete one too
+    // Note: Replacing content in an incomplete block might be unusual, but technically possible.
+    const allBlocks = [...completeBlocks, ...incompleteBlocks];
+
+    // Step 2: Validate index
+    if (blockIndex >= allBlocks.length) {
+        throw new Error(`blockIndex ${blockIndex} is out of bounds. Found ${allBlocks.length} blocks.`);
+    }
+
+    // Step 3: Get the target block's boundary information
+    const targetBlockBoundaries = allBlocks[blockIndex];
+    const openingFence = targetBlockBoundaries.opening;
+    const closingFence = targetBlockBoundaries.closing; // Will be undefined for incomplete blocks
+
+    if (!openingFence) {
+        // Should not happen if index is valid, but good practice to check
+        throw new Error(`Could not find opening fence for block at index ${blockIndex}.`);
+    }
+
+    // Determine the exact start and end of the full markdown block
+    const blockStartPos = openingFence.position;
+    // If the block is incomplete, the end is the end of the messageContent
+    const blockEndPos = closingFence
+        ? closingFence.position + closingFence.length
+        : messageContent.length;
+
+    // Step 4: Construct the replacement block string
+    const targetLanguage = language !== undefined ? language : (openingFence.language || ''); // Use provided language or original/empty
+    const newBlockString = `\`\`\`${targetLanguage}\n${newCodeContent}\n\`\`\``;
+
+    // Step 5: Perform the replacement
+    const updatedMessageContent =
+        messageContent.substring(0, blockStartPos) +
+        newBlockString +
+        messageContent.substring(blockEndPos);
+
+    return updatedMessageContent;
+}
+
+/**
+ * Replaces the content of a code block specified by its Block-UUID within a message string.
+ *
+ * @param {string} messageContent - The original message string containing code blocks.
+ * @param {string} blockUUID - The Block-UUID of the code block to replace.
+ * @param {string} newCodeContent - The new raw content (code, potentially including header) to insert into the block.
+ * @param {string} [language] - Optional: The language identifier for the updated code block fence. If omitted, the original language is preserved.
+ * @returns {string} The message content with the specified code block updated.
+ * @throws {Error} If no block with the specified UUID is found, or if multiple blocks have the same UUID.
+ */
+function updateCodeBlockByUUID(messageContent, blockUUID, newCodeContent, language = undefined) {
+    if (typeof messageContent !== 'string') {
+        throw new Error("messageContent must be a string.");
+    }
+    if (typeof blockUUID !== 'string' || !blockUUID) {
+        throw new Error("blockUUID must be a non-empty string.");
+    }
+    if (typeof newCodeContent !== 'string') {
+        throw new Error("newCodeContent must be a string.");
+    }
+
+    // Step 1: Process blocks to get headers and find the target index
+    const { blocks: processedBlocks, warnings } = processCodeBlocks(messageContent, { silent: true });
+
+    let targetIndex = -1;
+    let foundCount = 0;
+
+    for (let i = 0; i < processedBlocks.length; i++) {
+        const block = processedBlocks[i];
+        let match = false;
+
+        // Check standard code blocks by Block-UUID
+        if ((block.type === 'code') && block.header && block.header['Block-UUID'] === blockUUID) {
+            match = true;
+        }
+        // Check patch blocks by Target-Block-UUID
+        else if (block.type === 'patch' && block.metadata && block.metadata['Target-Block-UUID'] === blockUUID) {
+            match = true;
+        }
+
+        if (match) {
+            // If we've already found one, log a warning but still update the first one found.
+            if (targetIndex !== -1) {
+                console.warn(`Multiple blocks found matching UUID: ${blockUUID} (could be Block-UUID or Target-Block-UUID). Updating the first occurrence.`);
+            } else {
+                targetIndex = i;
+            }
+            foundCount++; // Increment count regardless to detect duplicates
+        }
+    }
+
+    // Step 2: Handle findings
+    if (targetIndex === -1) { // Use targetIndex to check if *any* valid match was set
+        throw new Error(`No code or patch block found matching UUID: ${blockUUID} (checked Block-UUID and Target-Block-UUID).`);
+    }
+    // Warning for multiple matches is handled inside the loop now.
+
+    // Step 3: Call the index-based function
+    // We need the index relative to *all* blocks (complete and incomplete), not just processed ones.
+    // Re-extract boundaries to get the correct index mapping.
+    const { openingPositions, closingPositions } = findAllCodeFences(messageContent);
+    const { completeBlocks, incompleteBlocks } = matchFencesAndExtractBlocks(
+        messageContent, openingPositions, closingPositions
+    );
+    const allBlocks = [...completeBlocks, ...incompleteBlocks];
+
+    // Find the index in the combined list that corresponds to the processed block's position
+    const targetProcessedBlock = processedBlocks[targetIndex];
+    const actualIndex = allBlocks.findIndex(b => b.opening.position === targetProcessedBlock.position);
+
+    if (actualIndex === -1) {
+        // This indicates a discrepancy between blockProcessor and blockExtractor results, which shouldn't happen.
+        throw new Error(`Internal error: Could not map processed block at index ${targetIndex} (matching UUID: ${blockUUID}) back to extracted block boundaries.`);
+    }
+
+    // Pass the optional language parameter down
+    return updateCodeBlockByIndex(messageContent, actualIndex, newCodeContent, language);
+}
+
+/**
+ * Updates a code block in message text identified by UUID.
+ * (Moved from original PatchUtils)
+ * @param {string} messageText - The original message text
+ * @param {string} blockUUID - The Block-UUID to update
+ * @param {string} newCode - The new code content (raw content, including header if applicable)
+ * @param {string} language - The code language for the fence
+ * @returns {string} Updated message text
+ * @throws {Error} If block not found or parameters missing.
+ */
+function updateCodeBlockInMessage(messageText, blockUUID, newCode, language) {
+    if (!messageText || !blockUUID || newCode === null || newCode === undefined) { // Allow empty string for newCode
+        throw new Error("Missing required parameters for updating code block (messageText, blockUUID, newCode)");
+    }
+
+    // Use findCodeBlockByUUID from blockExtractor
+    const block = findCodeBlockByUUID(messageText, blockUUID);
+
+    if (!block) {
+        throw new Error(`Code block with UUID ${blockUUID} not found`);
+    }
+
+    // Construct the new full block string
+    const newBlockString = '```' + (language || block.language) + '\n' + newCode + '\n```';
+
+    // Replace the old block with the new one using precise indices
+    return messageText.substring(0, block.startIndex) +
+           newBlockString +
+           messageText.substring(block.endIndex);
+}
+
+
+/**
+ * Generic router function to update a code block by index or UUID.
+ *
+ * @param {string} messageContent - The original message string.
+ * @param {number|string} identifier - The block index (number) or Block-UUID (string).
+ * @param {string} newCodeContent - The new raw content for the block.
+ * @param {string} [language] - Optional: The language identifier for the updated code block fence.
+ * @returns {string} The updated message content.
+ * @throws {Error} If the identifier type is invalid or if the underlying update function fails.
+ */
+function updateCodeBlock(messageContent, identifier, newCodeContent, language = undefined) {
+    if (typeof identifier === 'number') {
+        // Pass language to index-based function
+        return updateCodeBlockByIndex(messageContent, identifier, newCodeContent, language);
+    } else if (typeof identifier === 'string') {
+        // Pass language to UUID-based function
+        return updateCodeBlockByUUID(messageContent, identifier, newCodeContent, language);
+    } else {
+        throw new Error("Invalid identifier type. Must be a number (index) or a string (UUID).");
+    }
+}
+
+/**
+ * Deletes a code block specified by its index within a message string.
+ *
+ * @param {string} messageContent - The original message string containing code blocks.
+ * @param {number} blockIndex - The 0-based index of the code block to delete.
+ * @returns {string} The message content with the specified code block deleted.
+ * @throws {Error} If the blockIndex is out of bounds or if block boundaries cannot be determined.
+ */
+function deleteCodeBlockByIndex(messageContent, blockIndex) {
+    if (typeof messageContent !== 'string') {
+        throw new Error("messageContent must be a string.");
+    }
+    if (typeof blockIndex !== 'number' || blockIndex < 0) {
+        throw new Error("blockIndex must be a non-negative number.");
+    }
+
+    // Step 1: Find all fence positions to get accurate start/end of the full block
+    const { openingPositions, closingPositions } = findAllCodeFences(messageContent);
+    const { completeBlocks, incompleteBlocks } = matchFencesAndExtractBlocks(
+        messageContent, openingPositions, closingPositions
+    );
+
+    // Combine complete and incomplete for indexing
+    const allBlocks = [...completeBlocks, ...incompleteBlocks];
+
+    // Step 2: Validate index
+    if (blockIndex >= allBlocks.length) {
+        throw new Error(`blockIndex ${blockIndex} is out of bounds. Found ${allBlocks.length} blocks.`);
+    }
+
+    // Step 3: Get the target block's boundary information
+    const targetBlockBoundaries = allBlocks[blockIndex];
+    const openingFence = targetBlockBoundaries.opening;
+    const closingFence = targetBlockBoundaries.closing; // Will be undefined for incomplete blocks
+
+    if (!openingFence) {
+        // Should not happen if index is valid, but good practice to check
+        throw new Error(`Could not find opening fence for block at index ${blockIndex}.`);
+    }
+
+    // Determine the exact start and end of the full markdown block
+    const blockStartPos = openingFence.position;
+    // If the block is incomplete, the end is the end of the messageContent
+    const blockEndPos = closingFence
+        ? closingFence.position + closingFence.length
+        : messageContent.length;
+
+    // Step 4: Perform the deletion
+    const updatedMessageContent =
+        messageContent.substring(0, blockStartPos) +
+        messageContent.substring(blockEndPos);
+
+    return updatedMessageContent;
+}
+
+/**
+ * Deletes a code block specified by its Block-UUID within a message string.
+ *
+ * @param {string} messageContent - The original message string containing code blocks.
+ * @param {string} blockUUID - The Block-UUID of the code block to delete.
+ * @returns {string} The message content with the specified code block deleted.
+ * @throws {Error} If no block with the specified UUID is found, or if multiple blocks have the same UUID.
+ */
+function deleteCodeBlockByUUID(messageContent, blockUUID) {
+    if (typeof messageContent !== 'string') {
+        throw new Error("messageContent must be a string.");
+    }
+    if (typeof blockUUID !== 'string' || !blockUUID) {
+        throw new Error("blockUUID must be a non-empty string.");
+    }
+
+    // Step 1: Process blocks to get headers and find the target index
+    const { blocks: processedBlocks, warnings } = processCodeBlocks(messageContent, { silent: true });
+
+    let targetIndex = -1;
+    let foundCount = 0;
+
+    for (let i = 0; i < processedBlocks.length; i++) {
+        const block = processedBlocks[i];
+        let match = false;
+
+        // Check standard code blocks by Block-UUID
+        if (block.type === 'code' && block.header && block.header['Block-UUID'] === blockUUID) {
+            match = true;
+        }
+        // Check patch blocks by Target-Block-UUID
+        else if (block.type === 'patch' && block.metadata && block.metadata['Target-Block-UUID'] === blockUUID) {
+            match = true;
+        }
+
+        if (match) {
+            // If we've already found one, log a warning but still target the first one found.
+            if (targetIndex !== -1) {
+                console.warn(`Multiple blocks found matching UUID: ${blockUUID} (could be Block-UUID or Target-Block-UUID). Deleting the first occurrence.`);
+            } else {
+                targetIndex = i;
+            }
+            foundCount++; // Increment count regardless to detect duplicates
+        }
+    }
+
+    // Step 2: Handle findings
+    if (targetIndex === -1) { // Use targetIndex to check if *any* valid match was set
+        throw new Error(`No code or patch block found matching UUID: ${blockUUID} (checked Block-UUID and Target-Block-UUID).`);
+    }
+    // Warning for multiple matches is handled inside the loop now.
+
+    // Step 3: Call the index-based function
+    // We need the index relative to *all* blocks (complete and incomplete), not just processed ones.
+    // Re-extract boundaries to get the correct index mapping.
+    const { openingPositions, closingPositions } = findAllCodeFences(messageContent);
+    const { completeBlocks, incompleteBlocks } = matchFencesAndExtractBlocks(
+        messageContent, openingPositions, closingPositions
+    );
+    const allBlocks = [...completeBlocks, ...incompleteBlocks];
+
+    // Find the index in the combined list that corresponds to the processed block's position
+    const targetProcessedBlock = processedBlocks[targetIndex];
+    const actualIndex = allBlocks.findIndex(b => b.opening.position === targetProcessedBlock.position);
+
+    if (actualIndex === -1) {
+        // This indicates a discrepancy between blockProcessor and blockExtractor results, which shouldn't happen.
+        throw new Error(`Internal error: Could not map processed block at index ${targetIndex} (matching UUID: ${blockUUID}) back to extracted block boundaries.`);
+    }
+
+    return deleteCodeBlockByIndex(messageContent, actualIndex);
+}
+
+/**
+ * Generic router function to delete a code block by index or UUID.
+ *
+ * @param {string} messageContent - The original message string.
+ * @param {number|string} identifier - The block index (number) or Block-UUID (string).
+ * @returns {string} The updated message content.
+ * @throws {Error} If the identifier type is invalid or if the underlying delete function fails.
+ */
+function deleteCodeBlock(messageContent, identifier) {
+    if (typeof identifier === 'number') {
+        return deleteCodeBlockByIndex(messageContent, identifier);
+    } else if (typeof identifier === 'string') {
+        return deleteCodeBlockByUUID(messageContent, identifier);
+    } else {
+        throw new Error("Invalid identifier type. Must be a number (index) or a string (UUID).");
+    }
+}
+
+module.exports = {
+    updateCodeBlockByIndex,
+    updateCodeBlockByUUID,
+    updateCodeBlock,
+    updateCodeBlockInMessage,
+    deleteCodeBlockByIndex,
+    deleteCodeBlockByUUID,
+    deleteCodeBlock,
+};
+

package/src/CodeBlockUtils/uuidUtils.js

@@ -0,0 +1,48 @@
+/**
+ * Component: CodeBlockUtils UUID Utilities
+ * Block-UUID: 37525056-8d61-4501-bd9d-c098c19542a5
+ * Parent-UUID: 7e9d3f8a-1b2c-4d5e-8f9a-0123456789ab
+ * Version: 1.0.0
+ * Description: Provides utility functions for generating and validating RFC 4122 UUID v4 strings.
+ * Language: JavaScript
+ * Created-at: 2025-04-15T15:52:06.507Z
+ * Authors: Gemini 2.5 Pro (v1.0.0)
+ */
+
+
+/**
+ * Generates a valid RFC 4122 UUID v4
+ * @returns {string} A valid UUID v4
+ */
+function generateUUID() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}
+
+/**
+ * Validates UUID and returns object with validation results
+ * @param {string} uuid - The UUID string to validate
+ * @returns {Object} Object containing validation results and replacement UUID if needed
+ */
+function validateUUID(uuid) {
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+    if (!uuidPattern.test(uuid)) {
+        return {
+            "Block-UUID": "INVALID UUID",
+            "Correct Block-UUID": generateUUID()
+        };
+    }
+
+    return {
+        "Block-UUID": uuid
+    };
+}
+
+module.exports = {
+    generateUUID,
+    validateUUID
+};

package/src/ContextUtils.js

@@ -0,0 +1,180 @@
+/**
+ * Component: ContextUtils
+ * Block-UUID: c199efe3-003c-4226-af3c-d460392a6569
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions for parsing context message sections to extract file details and code blocks.
+ * Language: JavaScript
+ * Created-at: 2025-05-09T01:36:20.107Z
+ * Authors: Gemini 2.5 Flash Thinking (v1.0.0)
+ */
+
+
+const CodeBlockUtils = require('./CodeBlockUtils');
+const MessageUtils = require('./MessageUtils');
+
+/**
+ * Parses context details from a context message section.
+ * @param {string} sectionText - The text content of a single context section (starting from the file header).
+ * @returns {Object|null} An object with file details (name, path, meta, content) or null if parsing fails.
+ */
+function parseContextSection(sectionText) {
+    const contextSection = {
+        name: 'Unknown File',
+        content: null,
+        sectionText
+    };
+
+    // Extract filename from #### `filename` line
+    const nameMatch = sectionText.match(/^####\s*`([^`]+)`/);
+    if (nameMatch && nameMatch[1]) {
+        contextSection.name = nameMatch[1];
+    } else {
+        // Attempt fallback if format is slightly different, e.g., #### filename without backticks
+        const fallbackNameMatch = sectionText.match(/^####\s*([^\n]+)/);
+        if (fallbackNameMatch && fallbackNameMatch[1]) {
+            contextSection.name = fallbackNameMatch[1].trim();
+        } else {
+             console.warn("Could not parse filename from section head:", sectionText.split('\n')[0]);
+             // Keep default 'Unknown File' or decide to return null
+        }
+    }
+
+    // Extract metadata lines (simple approach: grab lines starting with '-')
+    const properties = ['repo', 'path', 'chat id', 'parent id', 'size', 'tokens', 'type'];
+    const lines = sectionText.split('\n').filter(line => line.trim().startsWith('-'));
+    const metaLines = [];
+    let stop = false;
+    lines.forEach(line => {
+        if (stop) return;
+
+        const trimmedLine = line.substring(1).trim(); // Remove '-' and trim
+        if (trimmedLine === '' || trimmedLine.startsWith('```')) {
+            stop = true;
+            return;
+        }
+
+        const property = trimmedLine.toLowerCase().split(':')[0];
+
+        if (properties.includes(property)) {
+            let value = trimmedLine.split(':').slice(1).join(':').trim();
+
+            if (property.match(/id/))
+                value = parseInt(value);
+
+            contextSection[property] = value;
+            metaLines.push(line);
+        }
+    });
+
+    const { blocks, warnings } = CodeBlockUtils.extractCodeBlocks(sectionText, { silent: true });
+    const codeBlocks = blocks.filter(block => block.type === 'code');
+
+    if (codeBlocks.length === 0) {
+        console.warn(`No code block found exists for ${contextSection.name}`);
+        throw("");
+    } else if (codeBlocks.length > 1) {
+        console.warn(`More than one code block found for ${contextSection.name}`);
+    } else {
+        const block = codeBlocks[0];
+        const { headerText, content, language, highlight } = block;
+        contextSection.content = (headerText ? headerText+'\n\n\n' : '')+content;
+        contextSection.language = language;
+        contextSection.highlight = highlight;
+        contextSection.block = block;
+        contextSection.header = metaLines.join('\n');
+    }
+
+    return contextSection;
+}
+
+/**
+ * Extracts and parses all context sections from a context message string.
+ * @param {string} messageContent - The full content of the context message.
+ * @returns {Array<Object>} An array of parsed context section objects.
+ * @throws {Error} If the message content is not a valid context message.
+ */
+function extractContextSections(messageContent) {
+    // Use the utility function to validate the message type
+    if (!MessageUtils.isContextMessage(messageContent)) {
+        throw new Error("Invalid message type: Content is not a context message.");
+    }
+
+    const contextSections = [];
+
+    // Split the message content into sections based the markers
+    const [summary, items] = messageContent.split(/\n---Start of Context---\n\n/);
+    const sections = items.split(/\n---End of Item---\n/);
+
+    // Process sections starting from the first potential path delimiter.
+    for (let i = 0; i < sections.length; i++) {
+        const contextSection = parseContextSection(sections[i]);
+
+        if (contextSection) {
+            contextSections.push(contextSection);
+        }
+    }
+
+    if (contextSections.length === 0) {
+         console.warn("Context message detected, but no context sections could be parsed by extractContextSections.");
+         // Depending on desired behavior, could throw an error or return empty array
+    }
+
+    return contextSections;
+}
+
+function extractContextItemsOverviewTableRows(messageContent) {
+    const lines = messageContent.trim().split('\n');
+    const startIndex = lines.findIndex(line => line.startsWith('---Start of Overview Items---')) + 4;
+
+    // A starting index of 2 means we never found it
+    if (startIndex === 3) {
+        return null;
+    }
+
+    const col2Field = {
+        1: 'chatId',
+        2: 'type', // file, tree, etc.
+        3: 'repoFullName', // owner/name => facebook/react
+        4: 'gitRef',  // branch name, commit ahs, etc.
+        5: 'gitPath', // relative repo path and not the chat path
+        6: 'purpose', // single sentence
+        7: 'keywords', // comma separated
+    };
+
+    const rows = [];
+
+    for (let i = startIndex; i < lines.length; i++ ) {
+        const line = lines[i];
+
+        // Since we are parsing a Markdown table, we expect the first line to be the vertical bar
+        if (!line.startsWith('|'))
+            break;
+
+        const values = line.split('|');
+        const row = {};
+
+        values.forEach((value, col) => {
+            if (col === 0)
+                return;
+
+            const field = col2Field[col];
+
+            if (!field)
+                return;
+
+            value = value.trim();
+            row[field] = field === 'chatId' ? parseInt(value) : value;
+        });
+
+        rows.push(row);
+    }
+
+    return rows;
+}
+
+module.exports = {
+    parseContextSection,
+    extractContextSections,
+    extractContextItemsOverviewTableRows
+};