@gitsense/gsc-utils 0.2.24 → 0.2.27

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.

package/src/CompactChatUtils/ReferenceMessageUtils.js

@@ -0,0 +1,143 @@
+/**
+ * Component: ReferenceMessageUtils
+ * Block-UUID: 2870551a-4311-4d64-9491-c9cc62f276e8
+ * Parent-UUID: N/A
+ * Description: Utility for parsing reference messages in the compact message workflow, extracting session data, metadata, and message sections.
+ * Language: JavaScript
+ * Created-at: 2025-12-07T00:08:42.573Z
+ * Authors: GLM-4.6 (v1.0.0)
+ */
+
+
+class ReferenceMessageUtils {
+    /**
+     * Extracts all data from a reference message including session data, metadata, and message sections
+     * @param {string} referenceMessage - The reference message content to parse
+     * @returns {Object} Parsed data with messages to compact and keep, metadata, and session information
+     */
+    static extractReferenceMessageData(referenceMessage) {
+        if (!referenceMessage) {
+            return {
+                messagesToCompact: [],
+                messagesToKeep: [],
+                originalChatUuid: null,
+                validationHash: null,
+                sessionId: null,
+                range: null,
+                from: null,
+                to: null
+            };
+        }
+
+        // Extract Original Chat UUID
+        const originalChatUuidMatch = referenceMessage.match(/Original Chat UUID:\s*([a-f0-9-]+)/i);
+        const originalChatUuid = originalChatUuidMatch ? originalChatUuidMatch[1] : null;
+
+        // Extract Validation Hash
+        const validationHashMatch = referenceMessage.match(/Validation Hash:\s*([a-f0-9]+)/i);
+        const validationHash = validationHashMatch ? validationHashMatch[1] : null;
+
+        // Extract Session ID
+        const sessionIdMatch = referenceMessage.match(/Session ID:\s*(\d+)/i);
+        const sessionId = sessionIdMatch ? sessionIdMatch[1] : null;
+
+        // Extract Range
+        const rangeMatch = referenceMessage.match(/Range:\s*(\d+-\d+)/i);
+        const range = rangeMatch ? rangeMatch[1] : null;
+
+        // Extract From and To values
+        const fromMatch = referenceMessage.match(/From:\s*(\d+)/i);
+        const from = fromMatch ? parseInt(fromMatch[1], 10) : null;
+
+        const toMatch = referenceMessage.match(/To:\s*(\d+)/i);
+        const to = toMatch ? parseInt(toMatch[1], 10) : null;
+
+        // If range is not found but from and to are available, construct the range
+        if (!range && from !== null && to !== null) {
+            range = `${from}-${to}`;
+        }
+
+        // Extract Messages to Compact section
+        const compactSectionMatch = referenceMessage.match(/# Messages to Compact\n([\s\S]*?)(?=\n# |\n$|$)/);
+        const compactSection = compactSectionMatch ? compactSectionMatch[1] : '';
+
+        // Extract Messages to Keep section
+        const keepSectionMatch = referenceMessage.match(/# Messages to Keep \(Context\)\n([\s\S]*?)(?=\n# |\n$|$)/);
+        const keepSection = keepSectionMatch ? keepSectionMatch[1] : '';
+
+        // Parse messages from each section
+        const messagesToCompact = this.parseMessageSection(compactSection);
+        const messagesToKeep = this.parseMessageSection(keepSection);
+
+        return {
+            messagesToCompact,
+            messagesToKeep,
+            originalChatUuid,
+            validationHash,
+            sessionId,
+            range,
+            from,
+            to
+        };
+    }
+
+    /**
+     * Parses a message section to extract individual messages
+     * @param {string} section - The section content to parse
+     * @returns {Array} Array of parsed message objects
+     */
+    static parseMessageSection(section) {
+        if (!section) return [];
+
+        const messages = [];
+        const messageRegex = /<(\w+) message number (\d+)>\n([\s\S]*?)\n<\/\1 message number \2>/g;
+        let match;
+
+        while ((match = messageRegex.exec(section)) !== null) {
+            const [, role, positionStr, content] = match;
+            const position = parseInt(positionStr, 10);
+
+            messages.push({
+                role,
+                position,
+                content: content.trim()
+            });
+        }
+
+        return messages;
+    }
+
+    /**
+     * Extracts just the metadata from a reference message without the message sections
+     * @param {string} referenceMessage - The reference message content to parse
+     * @returns {Object} Metadata object with original chat UUID, validation hash, session ID, and range information
+     */
+    static extractReferenceMessageMetadata(referenceMessage) {
+        const data = this.extractReferenceMessageData(referenceMessage);
+
+        return {
+            originalChatUuid: data.originalChatUuid,
+            validationHash: data.validationHash,
+            sessionId: data.sessionId,
+            range: data.range,
+            from: data.from,
+            to: data.to
+        };
+    }
+
+    /**
+     * Checks if a message is a reference message
+     * @param {string} message - The message content to check
+     * @returns {boolean} True if the message is a reference message
+     */
+    static isReferenceMessage(message) {
+        if (!message) return false;
+
+        // Check for key indicators of a reference message
+        return message.includes('# Compact Messages Reference') &&
+            message.includes('Original Chat UUID:') &&
+            message.includes('Session ID:');
+    }
+}
+
+module.exports = { ReferenceMessageUtils };

package/src/CompactChatUtils/index.js

@@ -0,0 +1,40 @@
+/**
+ * Component: CompactChatUtils Index
+ * Block-UUID: cd0a6091-edb6-4e92-9439-63dd8f6a6796
+ * Parent-UUID: 5ffa0338-b4fb-4968-908c-f23a26d4923b
+ * Version: 2.0.0
+ * Description: Entry point for CompactChatUtils that exports both ReferenceMessageUtils and CompactedMessageUtils methods directly for easier access.
+ * Language: JavaScript
+ * Created-at: 2025-12-07T00:10:05.123Z
+ * Authors: GLM-4.6 (v1.0.0), GLM-4.6 (v2.0.0)
+ */
+
+
+const { ReferenceMessageUtils } = require('./ReferenceMessageUtils');
+const { CompactedMessageUtils } = require('./CompactedMessageUtils');
+
+/**
+ * CompactChatUtils provides utilities for working with compacted messages in GitSense Chat.
+ * It includes functionality for parsing reference messages and formatting/parsing compacted messages.
+ */
+module.exports = {
+    // Export the classes for those who want to access them directly
+    ReferenceMessageUtils,
+    CompactedMessageUtils,
+    
+    // Export all methods from ReferenceMessageUtils directly
+    extractReferenceMessageData: ReferenceMessageUtils.extractReferenceMessageData,
+    parseMessageSection: ReferenceMessageUtils.parseMessageSection,
+    extractReferenceMessageMetadata: ReferenceMessageUtils.extractReferenceMessageMetadata,
+    isReferenceMessage: ReferenceMessageUtils.isReferenceMessage,
+    
+    // Export all methods from CompactedMessageUtils directly
+    formatCompactedMessage: CompactedMessageUtils.formatCompactedMessage,
+    extractCompactedMessageMetadata: CompactedMessageUtils.extractCompactedMessageMetadata,
+    extractCompactedMessageContent: CompactedMessageUtils.extractCompactedMessageContent,
+    validateCompactedMessageFormat: CompactedMessageUtils.validateCompactedMessageFormat,
+    isCompactedMessage: CompactedMessageUtils.isCompactedMessage,
+    isValidUUID: CompactedMessageUtils.isValidUUID,
+    isValidMessageRange: CompactedMessageUtils.isValidMessageRange,
+    isValidISOTimestamp: CompactedMessageUtils.isValidISOTimestamp
+};

package/src/ContextUtils.js

@@ -1,12 +1,12 @@
 /*
  * Component: ContextUtils
- * Block-UUID: a0b71292-b1cc-401a-8ce2-544a047b0fef
- * Parent-UUID: c018b1f9-2291-4bc9-9c4b-ab53a5db745e
- * Version: 1.3.0
+ * Block-UUID: 534c348d-a11f-4de6-ad15-f33068d51fb8
+ * Parent-UUID: a0b71292-b1cc-401a-8ce2-544a047b0fef
+ * Version: 1.4.0
  * Description: Provides utility functions for parsing context message sections to extract file details and code blocks, and for formatting content for LLM context.
  * Language: JavaScript
  * Created-at: 2025-05-09T01:36:20.107Z
- * Authors: Gemini 2.5 Flash Thinking (v1.0.0), Gemini 2.5 Flash (v1.1.0), Qwen 3 Coder 480B - Cerebras (v1.2.0), Qwen 3 Coder 480B - Cerebras (v1.3.0)
+ * Authors: Gemini 2.5 Flash Thinking (v1.0.0), Gemini 2.5 Flash (v1.1.0), Qwen 3 Coder 480B - Cerebras (v1.2.0), Qwen 3 Coder 480B - Cerebras (v1.3.0), Qwen 3 Coder 480B - Cerebras (v1.4.0)
  */
 
 
@@ -77,6 +77,41 @@ function _createContextSummary(items, contentType) {
     return summary + "\n";
 }
 
+/**
+ * Extracts all context files from a given chat object.
+ * Iterates through chat messages, identifies context loader outputs,
+ * and parses them into individual file objects.
+ *
+ * @param {object} chat - The GitSense chat object.
+ * @returns {Array<object>} An array of parsed context file objects.
+ *                           Returns an empty array if no context files are found or on error.
+ */
+function getContextFiles(chat) {
+    const ChatUtils = require('./ChatUtils');
+    const contextFiles = [];
+    const messages = ChatUtils.getChatMessages(chat);
+
+    if (!Array.isArray(messages)) {
+        console.warn("getContextFiles: Provided chat object does not contain a valid messages array.");
+        return contextFiles;
+    }
+
+    messages.forEach(message => {
+        // Check if the message content is a context message
+        if (MessageUtils.isContextMessage(message.message)) {
+            try {
+                // Extract all context sections from the message content
+                const extractedFiles = extractContextSections(message.message);
+                contextFiles.push(...extractedFiles);
+            } catch (error) {
+                console.warn(`getContextFiles: Failed to extract context sections from message ID ${message.id}:`, error);
+            }
+        }
+    });
+
+    return contextFiles;
+}
+
 /**
  * Escapes backticks in code blocks to prevent premature termination of LLM-generated code blocks.
  * @param {string} content - The content string to escape.
@@ -141,7 +176,7 @@ function parseContextSection(sectionText) {
         if (properties.includes(property)) {
             let value = trimmedLine.split(':').slice(1).join(':').trim();
 
-            if (property.match(/id/))
+            if (property.match(/id/) || property.match(/tokens/))
                 value = parseInt(value);
 
             contextSection[property] = value;
@@ -351,6 +386,7 @@ function formatContextContent(items, contentType, contentOption) {
 module.exports = {
     parseContextSection,
     extractContextSections,
+    getContextFiles,
     extractContextItemsOverviewTableRows,
     formatContextContent,
 };