@gitsense/gsc-utils 0.2.25 → 0.2.27

package/src/CodeBlockUtils/lineageTracer.js

@@ -0,0 +1,95 @@
+/**
+ * Component: CodeBlockUtils Lineage Tracer
+ * Block-UUID: 13b08cce-6fd1-4ec9-a915-240714ee89b9
+ * Parent-UUID: df1a629b-2cc0-4677-b410-3172ee0e0f9f
+ * Version: 1.1.0
+ * Description: Provides a utility function to trace the full lineage (patch-based and parent-based) of code blocks within a chat, including loop detection.
+ * Language: JavaScript
+ * Created-at: 2025-10-23T01:28:10.456Z
+ * Authors: Qwen 3 Coder 480B - Cerebras (v1.0.0), Qwen 3 Coder 480B - Cerebras (v1.1.0)
+ */
+
+
+/**
+ * Traces the full lineage of a code block or patch identified by a UUID.
+ * The lineage includes the block itself and all its ancestors, tracing backwards
+ * first through patch relationships (Source-Block-UUID -> Target-Block-UUID)
+ * and then through Parent-UUID relationships.
+ * Loop detection is included to prevent infinite tracing.
+ *
+ * @param {string} uuid - The UUID of the target code block or patch.
+ * @param {Map<string, object>} blockMap - A map where keys are UUIDs (for code blocks)
+ *                                         or patch UUIDs (source:target) and values
+ *                                         are the corresponding block objects.
+ *                                         Block objects are expected to have
+ *                                         properties like `isPatch`, `metadata`, and `header`.
+ * @returns {Array<object>} An array of block objects representing the lineage.
+ *                          The first element is the block for the provided `uuid`.
+ *                          Subsequent elements are its ancestors.
+ *                          Returns an empty array if the initial uuid is not found.
+ *                          If a loop is detected, the last element will have a property `loopDetected: true`.
+ */
+function getLineage(uuid, blockMap) {
+    if (!uuid || !blockMap) {
+        return [];
+    }
+
+    const lineage = [];
+    const visitedUuids = new Set();
+    let currentUuid = uuid;
+
+    while (currentUuid) {
+        // --- Loop Detection ---
+        if (visitedUuids.has(currentUuid)) {
+            // Add a marker or the block itself to indicate the loop
+            const loopBlock = blockMap.get(currentUuid) || { uuid: currentUuid, loopDetected: true, type: 'loop-marker' };
+            loopBlock.loopDetected = true; // Ensure the property is set
+            lineage.push(loopBlock);
+            break; // Stop the trace
+        }
+        visitedUuids.add(currentUuid);
+
+        // --- 1. Try to find the block directly by its UUID ---
+        let block = blockMap.get(currentUuid);
+
+        // --- 2. If not found directly, search patch keys ---
+        if (!block) {
+            for (const [key, value] of blockMap) {
+                // Check if the map key is a patch key (contains ':') and ends with our target UUID
+                if (key.includes(':') && key.endsWith(`:${currentUuid}`)) {
+                    block = value;
+                    break;
+                }
+            }
+        }
+
+        // --- 3. If a block was found, add it to the lineage ---
+        if (block) {
+            lineage.push(block);
+
+            let nextUuid = null;
+
+            // --- 3a. If it's a patch, move to its source UUID ---
+            if (block.isPatch && block.metadata && block.metadata['Source-Block-UUID']) {
+                nextUuid = block.metadata['Source-Block-UUID'];
+            }
+            // --- 3b. If it's a code block, move to its Parent-UUID (if valid) ---
+            else if (!block.isPatch && block.header && block.header['Parent-UUID'] && block.header['Parent-UUID'] !== 'N/A') {
+                 nextUuid = block.header['Parent-UUID'];
+            }
+// If it's a code block with Parent-UUID: 0c104865-260a-4942-8cb6-93bebf40c450
+
+            currentUuid = nextUuid;
+        } else {
+            // If no block is found for currentUuid, the lineage is incomplete.
+            // We could add a placeholder here if needed, but for now, we just stop.
+            currentUuid = null;
+        }
+    }
+
+    return lineage;
+}
+
+module.exports = {
+    getLineage
+};

package/src/CompactChatUtils/CompactedMessageUtils.js

@@ -0,0 +1,224 @@
+/**
+ * Component: CompactedMessageUtils
+ * Block-UUID: b4111118-ec11-49d6-9a6e-402ca0b6df5b
+ * Parent-UUID: N/A
+ * Version: 1.0.1
+ * Description: Utility for formatting, parsing, and validating compacted messages with standardized metadata headers.
+ * Language: JavaScript
+ * Created-at: 2025-12-07T00:09:15.842Z
+ * Authors: GLM-4.6 (v1.0.0), GLM-4.6 (v1.0.1)
+ */
+
+
+class CompactedMessageUtils {
+    /**
+     * Formats a compacted message with standardized metadata headers
+     * @param {string} content - The compacted message content
+     * @param {string} originalChatUuid - UUID of the original chat
+     * @param {string} messageRange - Message range that was compacted (e.g., "3-6")
+     * @param {Object} options - Additional options
+     * @param {Date} options.compactedAt - Custom timestamp for when the message was compacted
+     * @returns {string} Formatted compacted message with metadata
+     */
+    static formatCompactedMessage(content, originalChatUuid, messageRange, options = {}) {
+        if (!content) {
+            throw new Error('Content is required for formatting a compacted message');
+        }
+
+        if (!originalChatUuid) {
+            throw new Error('Original chat UUID is required for formatting a compacted message');
+        }
+
+        if (!messageRange) {
+            throw new Error('Message range is required for formatting a compacted message');
+        }
+
+        // Use provided timestamp or generate current one
+        const compactedAt = options.compactedAt || new Date().toISOString();
+
+        return `## Compacted Message
+
+- **Original Chat:** [${originalChatUuid}](/?chat=${originalChatUuid})
+- **Message Range:** ${messageRange}
+- **Compacted At:** ${compactedAt}
+
+${content}`;
+    }
+
+    /**
+     * Extracts metadata from a compacted message
+     * @param {string} compactedMessage - The compacted message to parse
+     * @returns {Object|null} Metadata object or null if format is invalid
+     */
+    static extractCompactedMessageMetadata(compactedMessage) {
+        if (!this.isCompactedMessage(compactedMessage)) {
+            return null;
+        }
+
+        // Extract Original Chat UUID
+        const originalChatMatch = compactedMessage.match(/\*\*Original Chat:\*\*\s*([a-f0-9-]+)/i);
+        const originalChatUuid = originalChatMatch ? originalChatMatch[1] : null;
+
+        // Extract Message Range
+        const rangeMatch = compactedMessage.match(/\*\*Message Range:\*\*\s*(\d+-\d+)/i);
+        const messageRange = rangeMatch ? rangeMatch[1] : null;
+
+        // Extract Compacted At timestamp
+        const compactedAtMatch = compactedMessage.match(/\*\*Compacted At:\*\*\s*([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z)/i);
+        const compactedAt = compactedAtMatch ? compactedAtMatch[1] : null;
+
+        return {
+            originalChatUuid,
+            messageRange,
+            compactedAt
+        };
+    }
+
+    /**
+     * Extracts just the content portion from a compacted message (without metadata)
+     * @param {string} compactedMessage - The compacted message to parse
+     * @returns {string|null} Content portion or null if format is invalid
+     */
+    static extractCompactedMessageContent(compactedMessage) {
+        if (!this.isCompactedMessage(compactedMessage)) {
+            return null;
+        }
+
+        // Find the start and end boundaries
+        const startMarker = "## Compacted Message";
+        const endMarker = "## End Compacted Message";
+        
+        const startIndex = compactedMessage.indexOf(startMarker);
+        const endIndex = compactedMessage.indexOf(endMarker);
+        
+        // If start marker is not found, return null
+        if (startIndex === -1) {
+            return null;
+        }
+        
+        // If end marker is not found, extract everything after start marker
+        if (endIndex === -1) {
+            return compactedMessage.substring(startIndex + startMarker.length).trim();
+        }
+        
+        // Extract content between the markers
+        const contentStart = startIndex + startMarker.length;
+        return compactedMessage.substring(contentStart, endIndex).trim();
+    }
+
+    /**
+     * Validates that a compacted message follows the expected format
+     * @param {string} compactedMessage - The compacted message to validate
+     * @returns {Object} Validation result with isValid flag and any errors/warnings
+     */
+    static validateCompactedMessageFormat(compactedMessage) {
+        const result = {
+            isValid: true,
+            errors: [],
+            warnings: []
+        };
+
+        if (!compactedMessage) {
+            result.isValid = false;
+            result.errors.push('Compacted message is empty or null');
+            return result;
+        }
+
+        // Check for required header
+        if (!compactedMessage.includes('## Compacted Message')) {
+            result.isValid = false;
+            result.errors.push('Missing required "## Compacted Message" header');
+        }
+
+        // Check for required metadata fields
+        const metadata = this.extractCompactedMessageMetadata(compactedMessage);
+
+        if (!metadata) {
+            result.isValid = false;
+            result.errors.push('Could not extract metadata from compacted message');
+            return result;
+        }
+
+        if (!metadata.originalChatUuid) {
+            result.isValid = false;
+            result.errors.push('Missing or invalid Original Chat UUID');
+        }
+
+        if (!metadata.messageRange) {
+            result.isValid = false;
+            result.errors.push('Missing or invalid Message Range');
+        }
+
+        if (!metadata.compactedAt) {
+            result.warnings.push('Missing or invalid Compacted At timestamp');
+        }
+
+        // Validate UUID format
+        if (metadata.originalChatUuid && !this.isValidUUID(metadata.originalChatUuid)) {
+            result.isValid = false;
+            result.errors.push('Original Chat UUID is not in valid UUID format');
+        }
+
+        // Validate message range format
+        if (metadata.messageRange && !this.isValidMessageRange(metadata.messageRange)) {
+            result.isValid = false;
+            result.errors.push('Message Range is not in valid format (expected "X-Y")');
+        }
+
+        // Validate timestamp format
+        if (metadata.compactedAt && !this.isValidISOTimestamp(metadata.compactedAt)) {
+            result.warnings.push('Compacted At timestamp is not in valid ISO 8601 format');
+        }
+
+        return result;
+    }
+
+    /**
+     * Checks if a message is a compacted message
+     * @param {string} message - The message content to check
+     * @returns {boolean} True if the message is a compacted message
+     */
+    static isCompactedMessage(message) {
+        if (!message) return false;
+
+        // Check for the compacted message header
+        return message.includes('## Compacted Message');
+    }
+
+    /**
+     * Validates if a string is a valid UUID v4
+     * @param {string} uuid - The UUID string to validate
+     * @returns {boolean} True if valid UUID v4
+     */
+    static isValidUUID(uuid) {
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        return uuidRegex.test(uuid);
+    }
+
+    /**
+     * Validates if a string is a valid message range (e.g., "3-6")
+     * @param {string} range - The range string to validate
+     * @returns {boolean} True if valid range format
+     */
+    static isValidMessageRange(range) {
+        const rangeRegex = /^\d+-\d+$/;
+        if (!rangeRegex.test(range)) return false;
+
+        const [from, to] = range.split('-').map(Number);
+        return !isNaN(from) && !isNaN(to) && from <= to;
+    }
+
+    /**
+     * Validates if a string is a valid ISO 8601 timestamp
+     * @param {string} timestamp - The timestamp string to validate
+     * @returns {boolean} True if valid ISO 8601 timestamp
+     */
+    static isValidISOTimestamp(timestamp) {
+        if (!timestamp) return false;
+
+        const date = new Date(timestamp);
+        return !isNaN(date.getTime()) && timestamp === date.toISOString();
+    }
+}
+
+module.exports = { CompactedMessageUtils };

package/src/CompactChatUtils/README.md

@@ -0,0 +1,321 @@
+# CompactChatUtils
+
+A utility module for working with compacted messages in GitSense Chat. This module provides functionality for parsing reference messages, formatting compacted messages, and validating message formats.
+
+## Overview
+
+CompactChatUtils is designed to handle the compact message workflow in GitSense Chat, which allows for efficient storage and retrieval of chat messages by compacting older messages while preserving context. The module consists of two main utility classes:
+
+- **ReferenceMessageUtils**: Parses reference messages that contain information about which messages to compact and which to keep as context
+- **CompactedMessageUtils**: Formats, parses, and validates compacted messages with standardized metadata headers
+
+## Installation
+
+```javascript
+const { CompactChatUtils } = require('@gitsense/gsc-utils');
+```
+
+Or import individual utilities:
+
+```javascript
+const { ReferenceMessageUtils } = require('@gitsense/gsc-utils');
+const { CompactedMessageUtils } = require('@gitsense/gsc-utils');
+```
+
+## API Reference
+
+### ReferenceMessageUtils
+
+#### `extractReferenceMessageData(referenceMessage)`
+
+Extracts all data from a reference message including session data, metadata, and message sections.
+
+**Parameters:**
+- `referenceMessage` (string): The reference message content to parse
+
+**Returns:**
+- Object: Parsed data with messages to compact and keep, metadata, and session information
+
+**Example:**
+```javascript
+const data = ReferenceMessageUtils.extractReferenceMessageData(referenceMessage);
+console.log(data.messagesToCompact);
+console.log(data.originalChatUuid);
+```
+
+#### `parseMessageSection(section)`
+
+Parses a message section to extract individual messages.
+
+**Parameters:**
+- `section` (string): The section content to parse
+
+**Returns:**
+- Array: Array of parsed message objects
+
+**Example:**
+```javascript
+const messages = ReferenceMessageUtils.parseMessageSection(section);
+```
+
+#### `extractReferenceMessageMetadata(referenceMessage)`
+
+Extracts just the metadata from a reference message without the message sections.
+
+**Parameters:**
+- `referenceMessage` (string): The reference message content to parse
+
+**Returns:**
+- Object: Metadata object with original chat UUID, validation hash, session ID, and range information
+
+**Example:**
+```javascript
+const metadata = ReferenceMessageUtils.extractReferenceMessageMetadata(referenceMessage);
+console.log(metadata.originalChatUuid);
+```
+
+#### `isReferenceMessage(message)`
+
+Checks if a message is a reference message.
+
+**Parameters:**
+- `message` (string): The message content to check
+
+**Returns:**
+- boolean: True if the message is a reference message
+
+**Example:**
+```javascript
+if (ReferenceMessageUtils.isReferenceMessage(message)) {
+  // Handle reference message
+}
+```
+
+### CompactedMessageUtils
+
+#### `formatCompactedMessage(content, originalChatUuid, messageRange, options)`
+
+Formats a compacted message with standardized metadata headers.
+
+**Parameters:**
+- `content` (string): The compacted message content
+- `originalChatUuid` (string): UUID of the original chat
+- `messageRange` (string): Message range that was compacted (e.g., "3-6")
+- `options` (Object, optional): Additional options
+  - `compactedAt` (Date): Custom timestamp for when the message was compacted
+
+**Returns:**
+- string: Formatted compacted message with metadata
+
+**Example:**
+```javascript
+const compactedMessage = CompactedMessageUtils.formatCompactedMessage(
+  content, 
+  '123e4567-e89b-12d3-a456-426614174000', 
+  '3-6'
+);
+```
+
+#### `extractCompactedMessageMetadata(compactedMessage)`
+
+Extracts metadata from a compacted message.
+
+**Parameters:**
+- `compactedMessage` (string): The compacted message to parse
+
+**Returns:**
+- Object|null: Metadata object or null if format is invalid
+
+**Example:**
+```javascript
+const metadata = CompactedMessageUtils.extractCompactedMessageMetadata(compactedMessage);
+console.log(metadata.originalChatUuid);
+```
+
+#### `extractCompactedMessageContent(compactedMessage)`
+
+Extracts just the content portion from a compacted message (without metadata).
+
+**Parameters:**
+- `compactedMessage` (string): The compacted message to parse
+
+**Returns:**
+- string|null: Content portion or null if format is invalid
+
+**Example:**
+```javascript
+const content = CompactedMessageUtils.extractCompactedMessageContent(compactedMessage);
+```
+
+#### `validateCompactedMessageFormat(compactedMessage)`
+
+Validates that a compacted message follows the expected format.
+
+**Parameters:**
+- `compactedMessage` (string): The compacted message to validate
+
+**Returns:**
+- Object: Validation result with isValid flag and any errors/warnings
+
+**Example:**
+```javascript
+const validation = CompactedMessageUtils.validateCompactedMessageFormat(compactedMessage);
+if (validation.isValid) {
+  // Process valid compacted message
+} else {
+  console.error(validation.errors);
+}
+```
+
+#### `isCompactedMessage(message)`
+
+Checks if a message is a compacted message.
+
+**Parameters:**
+- `message` (string): The message content to check
+
+**Returns:**
+- boolean: True if the message is a compacted message
+
+**Example:**
+```javascript
+if (CompactedMessageUtils.isCompactedMessage(message)) {
+  // Handle compacted message
+}
+```
+
+#### `isValidUUID(uuid)`
+
+Validates if a string is a valid UUID v4.
+
+**Parameters:**
+- `uuid` (string): The UUID string to validate
+
+**Returns:**
+- boolean: True if valid UUID v4
+
+**Example:**
+```javascript
+if (CompactedMessageUtils.isValidUUID(uuid)) {
+  // Process valid UUID
+}
+```
+
+#### `isValidMessageRange(range)`
+
+Validates if a string is a valid message range (e.g., "3-6").
+
+**Parameters:**
+- `range` (string): The range string to validate
+
+**Returns:**
+- boolean: True if valid range format
+
+**Example:**
+```javascript
+if (CompactedMessageUtils.isValidMessageRange(range)) {
+  // Process valid range
+}
+```
+
+#### `isValidISOTimestamp(timestamp)`
+
+Validates if a string is a valid ISO 8601 timestamp.
+
+**Parameters:**
+- `timestamp` (string): The timestamp string to validate
+
+**Returns:**
+- boolean: True if valid ISO 8601 timestamp
+
+**Example:**
+```javascript
+if (CompactedMessageUtils.isValidISOTimestamp(timestamp)) {
+  // Process valid timestamp
+}
+```
+
+## Usage Examples
+
+### Parsing a Reference Message
+
+```javascript
+const { ReferenceMessageUtils } = require('@gitsense/gsc-utils');
+
+// Parse a reference message to extract data
+const referenceData = ReferenceMessageUtils.extractReferenceMessageData(referenceMessage);
+
+// Access the extracted data
+const { messagesToCompact, messagesToKeep, originalChatUuid, range } = referenceData;
+
+console.log(`Original Chat UUID: ${originalChatUuid}`);
+console.log(`Messages to compact: ${messagesToCompact.length}`);
+console.log(`Messages to keep: ${messagesToKeep.length}`);
+```
+
+### Formatting a Compacted Message
+
+```javascript
+const { CompactedMessageUtils } = require('@gitsense/gsc-utils');
+
+// Format a compacted message with metadata
+const compactedMessage = CompactedMessageUtils.formatCompactedMessage(
+  "This is the compacted content...",
+  "123e4567-e89b-12d3-a456-426614174000",
+  "3-6",
+  { compactedAt: new Date() }
+);
+
+console.log(compactedMessage);
+```
+
+### Validating a Compacted Message
+
+```javascript
+const { CompactedMessageUtils } = require('@gitsense/gsc-utils');
+
+// Validate a compacted message
+const validation = CompactedMessageUtils.validateCompactedMessageFormat(compactedMessage);
+
+if (!validation.isValid) {
+  console.error("Validation errors:");
+  validation.errors.forEach(error => console.error(`- ${error}`));
+  
+  if (validation.warnings.length > 0) {
+    console.warn("Validation warnings:");
+    validation.warnings.forEach(warning => console.warn(`- ${warning}`));
+  }
+}
+```
+
+### Using the Combined Interface
+
+```javascript
+const { CompactChatUtils } = require('@gitsense/gsc-utils');
+
+// Check if a message is a reference message
+if (CompactChatUtils.isReferenceMessage(message)) {
+  const data = CompactChatUtils.extractReferenceMessageData(message);
+  // Process reference message data
+}
+
+// Check if a message is a compacted message
+if (CompactChatUtils.isCompactedMessage(message)) {
+  const metadata = CompactChatUtils.extractCompactedMessageMetadata(message);
+  // Process compacted message metadata
+}
+```
+
+## File Structure
+
+```
+src/CompactChatUtils/
+├── index.js                 # Main entry point that exports all utilities
+├── ReferenceMessageUtils.js # Utilities for parsing reference messages
+├── CompactedMessageUtils.js # Utilities for compacted messages
+└── README.md               # This documentation
+```
+
+## Dependencies
+
+The CompactChatUtils module has no external dependencies and is part of the larger `@gitsense/gsc-utils` package.