@dotsetlabs/bellwether 0.10.0

package/dist/utils/jsonpath.js

@@ -0,0 +1,326 @@
+/**
+ * JSONPath parsing utilities.
+ *
+ * Supports a subset of JSONPath syntax for accessing nested values:
+ * - Dot notation: "foo.bar.baz"
+ * - Bracket notation: "foo['bar']" or "foo[\"bar\"]"
+ * - Array indices: "items[0]" or "items['0']"
+ * - Mixed: "foo.items[0].bar"
+ * - Escaped characters: "foo['bar.baz']" for keys containing dots
+ * - Special characters: "foo['key with spaces']" or "foo['key\"with\"quotes']"
+ */
+/**
+ * Parse a JSONPath expression into segments.
+ *
+ * @param path - The JSONPath expression to parse
+ * @returns ParseResult with segments or error
+ */
+export function parsePath(path) {
+    if (!path || path.length === 0) {
+        return { segments: [], error: 'Empty path' };
+    }
+    const segments = [];
+    let i = 0;
+    // Handle optional root ($)
+    if (path[0] === '$') {
+        i++;
+        // Skip optional leading dot after $
+        if (path[i] === '.') {
+            i++;
+        }
+    }
+    while (i < path.length) {
+        // Skip leading dot (for dot notation)
+        if (path[i] === '.') {
+            i++;
+            if (i >= path.length) {
+                return { segments, error: 'Unexpected end after dot' };
+            }
+        }
+        // Handle bracket notation
+        if (path[i] === '[') {
+            const result = parseBracket(path, i);
+            if (result.error) {
+                return { segments, error: result.error };
+            }
+            segments.push(result.segment);
+            i = result.endIndex;
+        }
+        // Handle property name (dot notation)
+        else {
+            const result = parseProperty(path, i);
+            if (result.error) {
+                return { segments, error: result.error };
+            }
+            segments.push(result.segment);
+            i = result.endIndex;
+        }
+    }
+    return { segments };
+}
+/**
+ * Parse a bracket expression starting at the given index.
+ */
+function parseBracket(path, start) {
+    // Skip the opening bracket
+    let i = start + 1;
+    // Skip whitespace
+    while (i < path.length && isWhitespace(path[i])) {
+        i++;
+    }
+    if (i >= path.length) {
+        return { endIndex: i, error: 'Unexpected end in bracket expression' };
+    }
+    // Check for string literal (single or double quotes)
+    if (path[i] === "'" || path[i] === '"') {
+        const quote = path[i];
+        i++;
+        let value = '';
+        while (i < path.length && path[i] !== quote) {
+            // Handle escape sequences
+            if (path[i] === '\\' && i + 1 < path.length) {
+                const next = path[i + 1];
+                if (next === quote || next === '\\') {
+                    value += next;
+                    i += 2;
+                    continue;
+                }
+                // Handle common escape sequences
+                if (next === 'n') {
+                    value += '\n';
+                    i += 2;
+                    continue;
+                }
+                if (next === 't') {
+                    value += '\t';
+                    i += 2;
+                    continue;
+                }
+                if (next === 'r') {
+                    value += '\r';
+                    i += 2;
+                    continue;
+                }
+            }
+            value += path[i];
+            i++;
+        }
+        if (i >= path.length) {
+            return { endIndex: i, error: `Unterminated string in bracket expression` };
+        }
+        // Skip the closing quote
+        i++;
+        // Skip whitespace before closing bracket
+        while (i < path.length && isWhitespace(path[i])) {
+            i++;
+        }
+        if (i >= path.length || path[i] !== ']') {
+            return { endIndex: i, error: 'Expected closing bracket' };
+        }
+        // Skip the closing bracket
+        i++;
+        return {
+            segment: { type: 'bracket_property', value },
+            endIndex: i,
+        };
+    }
+    // Check for numeric index
+    let numStr = '';
+    while (i < path.length && isDigit(path[i])) {
+        numStr += path[i];
+        i++;
+    }
+    if (numStr.length > 0) {
+        // Skip whitespace before closing bracket
+        while (i < path.length && isWhitespace(path[i])) {
+            i++;
+        }
+        if (i >= path.length || path[i] !== ']') {
+            return { endIndex: i, error: 'Expected closing bracket after index' };
+        }
+        // Skip the closing bracket
+        i++;
+        return {
+            segment: { type: 'index', value: parseInt(numStr, 10) },
+            endIndex: i,
+        };
+    }
+    // Invalid bracket content
+    return { endIndex: i, error: 'Invalid bracket expression: expected string or number' };
+}
+/**
+ * Parse a property name in dot notation starting at the given index.
+ */
+function parseProperty(path, start) {
+    let i = start;
+    let name = '';
+    // Property names can contain alphanumeric, underscore, hyphen, and dollar sign
+    // They cannot start with a digit
+    while (i < path.length && isPropertyChar(path[i])) {
+        name += path[i];
+        i++;
+    }
+    if (name.length === 0) {
+        return {
+            endIndex: i,
+            error: `Invalid character at position ${start}: ${path[start]}`,
+        };
+    }
+    return {
+        segment: { type: 'property', value: name },
+        endIndex: i,
+    };
+}
+/**
+ * Check if a character is a valid property name character.
+ */
+function isPropertyChar(char) {
+    const code = char.charCodeAt(0);
+    // alphanumeric, underscore, dollar sign, hyphen
+    return ((code >= 65 && code <= 90) || // A-Z
+        (code >= 97 && code <= 122) || // a-z
+        (code >= 48 && code <= 57) || // 0-9
+        code === 95 || // _
+        code === 36 || // $
+        code === 45 // -
+    );
+}
+/**
+ * Check if a character is a digit.
+ */
+function isDigit(char) {
+    const code = char.charCodeAt(0);
+    return code >= 48 && code <= 57;
+}
+/**
+ * Check if a character is whitespace.
+ */
+function isWhitespace(char) {
+    return char === ' ' || char === '\t' || char === '\n' || char === '\r';
+}
+/**
+ * Get a value from an object using a parsed path.
+ *
+ * @param obj - The object to access
+ * @param segments - The parsed path segments
+ * @returns The value at the path, or undefined if not found
+ */
+export function getValueBySegments(obj, segments) {
+    let current = obj;
+    for (const segment of segments) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        if (segment.type === 'index') {
+            if (!Array.isArray(current)) {
+                return undefined;
+            }
+            current = current[segment.value];
+        }
+        else {
+            // Both 'property' and 'bracket_property' access object keys
+            current = current[segment.value];
+        }
+    }
+    return current;
+}
+/**
+ * Get a value from an object using a JSONPath expression.
+ *
+ * This is the main API function combining parsing and value retrieval.
+ *
+ * @param obj - The object to access
+ * @param path - The JSONPath expression
+ * @returns The value at the path, or undefined if not found or path is invalid
+ *
+ * @example
+ * // Simple paths
+ * getValueAtPath({ a: { b: 1 } }, 'a.b') // => 1
+ *
+ * @example
+ * // Array access
+ * getValueAtPath({ items: [1, 2, 3] }, 'items[1]') // => 2
+ *
+ * @example
+ * // Keys with dots
+ * getValueAtPath({ 'key.with.dots': 42 }, "['key.with.dots']") // => 42
+ *
+ * @example
+ * // Keys with spaces
+ * getValueAtPath({ 'my key': 'value' }, "['my key']") // => 'value'
+ */
+export function getValueAtPath(obj, path) {
+    if (!path || typeof obj !== 'object' || obj === null) {
+        return undefined;
+    }
+    const parseResult = parsePath(path);
+    if (parseResult.error) {
+        return undefined;
+    }
+    return getValueBySegments(obj, parseResult.segments);
+}
+/**
+ * Check if a path is valid JSONPath syntax.
+ *
+ * @param path - The path to validate
+ * @returns True if the path is valid, false otherwise
+ */
+export function isValidPath(path) {
+    const result = parsePath(path);
+    return !result.error;
+}
+/**
+ * Convert a JSONPath expression to a normalized form.
+ * Useful for comparing paths that may use different notations.
+ *
+ * @param path - The path to normalize
+ * @returns Normalized path string, or the original if parsing fails
+ */
+export function normalizePath(path) {
+    const result = parsePath(path);
+    if (result.error) {
+        return path;
+    }
+    return result.segments
+        .map((seg) => {
+        if (seg.type === 'index') {
+            return `[${seg.value}]`;
+        }
+        // Use bracket notation for properties with special characters
+        const value = seg.value;
+        if (needsBracketNotation(value)) {
+            return `['${escapeString(value)}']`;
+        }
+        return `.${value}`;
+    })
+        .join('')
+        .replace(/^\./, ''); // Remove leading dot
+}
+/**
+ * Check if a property name needs bracket notation.
+ */
+function needsBracketNotation(name) {
+    if (name.length === 0)
+        return true;
+    // Check first character (can't be a digit)
+    const first = name.charCodeAt(0);
+    if (first >= 48 && first <= 57)
+        return true;
+    // Check all characters
+    for (let i = 0; i < name.length; i++) {
+        if (!isPropertyChar(name[i])) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Escape a string for use in bracket notation.
+ */
+function escapeString(str) {
+    return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+//# sourceMappingURL=jsonpath.js.map

package/dist/utils/markdown.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Markdown output escaping utilities.
+ *
+ * Provides functions to safely escape content for Markdown output,
+ * including tables, code blocks, and Mermaid diagrams.
+ */
+/**
+ * Escape a string for use in a Markdown table cell.
+ * Handles pipe characters and other special characters that break table structure.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for table cells
+ */
+export declare function escapeTableCell(text: string): string;
+/**
+ * Escape a string for use inside a code block.
+ * Handles backticks that would prematurely close the code block.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for code blocks
+ */
+export declare function escapeCodeBlock(text: string): string;
+/**
+ * Escape a string for use in a Mermaid diagram.
+ * Handles quotes, brackets, and other special characters.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for Mermaid
+ */
+export declare function escapeMermaid(text: string): string;
+/**
+ * Escape a string for use as a Mermaid node label.
+ * Wraps in quotes and escapes special characters.
+ *
+ * @param text - The text to use as a label
+ * @returns Safe Mermaid node label
+ */
+export declare function mermaidLabel(text: string): string;
+/**
+ * Options for JSON code block validation.
+ */
+export interface JsonCodeBlockOptions {
+    /** Maximum length before truncating (default: unlimited) */
+    maxLength?: number;
+    /** Truncation indicator (default: '...(truncated)') */
+    truncationIndicator?: string;
+    /** Whether to pretty-print the JSON (default: true) */
+    prettyPrint?: boolean;
+    /** Indentation for pretty-printing (default: 2) */
+    indent?: number;
+}
+/**
+ * Result of validating JSON for a code block.
+ */
+export interface JsonCodeBlockResult {
+    /** Whether the JSON is valid */
+    valid: boolean;
+    /** The formatted JSON string (or original if invalid) */
+    content: string;
+    /** Whether the content was truncated */
+    truncated: boolean;
+    /** Error message if JSON is invalid */
+    error?: string;
+}
+/**
+ * Validate and format JSON for output in a code block.
+ * Returns safe content even if JSON is invalid.
+ *
+ * @param json - The JSON string or object to validate
+ * @param options - Formatting options
+ * @returns Validation result with safe content
+ */
+export declare function validateJsonForCodeBlock(json: string | unknown, options?: JsonCodeBlockOptions): JsonCodeBlockResult;
+/**
+ * Escape special characters in inline code.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for inline code
+ */
+export declare function escapeInlineCode(text: string): string;
+/**
+ * Escape text for use in a Markdown link title.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for link titles
+ */
+export declare function escapeLinkTitle(text: string): string;
+/**
+ * Escape text for use in a Markdown bullet list item.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for list items
+ */
+export declare function escapeListItem(text: string): string;
+/**
+ * Wrap text to ensure it fits within table cell width constraints.
+ *
+ * @param text - The text to wrap
+ * @param maxWidth - Maximum width (default: 50)
+ * @returns Wrapped text with <br> for line breaks
+ */
+export declare function wrapTableCell(text: string, maxWidth?: number): string;
+/**
+ * Build a Markdown table from headers and rows.
+ * Automatically escapes cell content.
+ *
+ * @param headers - Array of header strings
+ * @param rows - 2D array of cell values
+ * @param alignments - Optional array of column alignments ('left', 'center', 'right')
+ * @returns Complete Markdown table string
+ */
+export declare function buildTable(headers: string[], rows: string[][], alignments?: Array<'left' | 'center' | 'right'>): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/utils/markdown.js

@@ -0,0 +1,265 @@
+/**
+ * Markdown output escaping utilities.
+ *
+ * Provides functions to safely escape content for Markdown output,
+ * including tables, code blocks, and Mermaid diagrams.
+ */
+import { DISPLAY_LIMITS } from '../constants.js';
+/**
+ * Escape a string for use in a Markdown table cell.
+ * Handles pipe characters and other special characters that break table structure.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for table cells
+ */
+export function escapeTableCell(text) {
+    if (!text)
+        return '';
+    return text
+        // Escape pipe characters (break table columns)
+        .replace(/\|/g, '\\|')
+        // Escape newlines (break table rows)
+        .replace(/\r?\n/g, '<br>')
+        // Escape leading/trailing whitespace that might affect rendering
+        .trim();
+}
+/**
+ * Escape a string for use inside a code block.
+ * Handles backticks that would prematurely close the code block.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for code blocks
+ */
+export function escapeCodeBlock(text) {
+    if (!text)
+        return '';
+    // Replace triple backticks with escaped version
+    // Use Unicode zero-width space to break the sequence
+    return text.replace(/```/g, '`\u200B`\u200B`');
+}
+/**
+ * Escape a string for use in a Mermaid diagram.
+ * Handles quotes, brackets, and other special characters.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for Mermaid
+ */
+export function escapeMermaid(text) {
+    if (!text)
+        return '';
+    return text
+        // Escape double quotes (break Mermaid string literals)
+        .replace(/"/g, '#quot;')
+        // Escape square brackets (node syntax)
+        .replace(/\[/g, '#lsqb;')
+        .replace(/\]/g, '#rsqb;')
+        // Escape parentheses (node syntax)
+        .replace(/\(/g, '#lpar;')
+        .replace(/\)/g, '#rpar;')
+        // Escape curly braces (subgraph syntax)
+        .replace(/\{/g, '#lcub;')
+        .replace(/\}/g, '#rcub;')
+        // Escape arrows and pipes
+        .replace(/-->/g, '#arrow;')
+        .replace(/->/g, '#rarr;')
+        .replace(/\|/g, '#pipe;')
+        // Escape newlines
+        .replace(/\r?\n/g, ' ');
+}
+/**
+ * Escape a string for use as a Mermaid node label.
+ * Wraps in quotes and escapes special characters.
+ *
+ * @param text - The text to use as a label
+ * @returns Safe Mermaid node label
+ */
+export function mermaidLabel(text) {
+    if (!text)
+        return '""';
+    // For simple alphanumeric text, no escaping needed
+    if (/^[a-zA-Z0-9_-]+$/.test(text)) {
+        return text;
+    }
+    // Escape and wrap in quotes for complex text
+    const escaped = text
+        .replace(/"/g, "'")
+        .replace(/\r?\n/g, ' ')
+        .trim();
+    return `"${escaped}"`;
+}
+/**
+ * Validate and format JSON for output in a code block.
+ * Returns safe content even if JSON is invalid.
+ *
+ * @param json - The JSON string or object to validate
+ * @param options - Formatting options
+ * @returns Validation result with safe content
+ */
+export function validateJsonForCodeBlock(json, options = {}) {
+    const { maxLength, truncationIndicator = '...(truncated)', prettyPrint = true, indent = 2, } = options;
+    let content;
+    let valid = true;
+    let error;
+    // Parse if string, stringify if object
+    if (typeof json === 'string') {
+        try {
+            const parsed = JSON.parse(json);
+            content = prettyPrint
+                ? JSON.stringify(parsed, null, indent)
+                : JSON.stringify(parsed);
+        }
+        catch (e) {
+            valid = false;
+            error = e instanceof Error ? e.message : 'Invalid JSON';
+            content = escapeCodeBlock(json);
+        }
+    }
+    else {
+        try {
+            content = prettyPrint
+                ? JSON.stringify(json, null, indent)
+                : JSON.stringify(json);
+        }
+        catch (e) {
+            valid = false;
+            error = e instanceof Error ? e.message : 'Cannot stringify value';
+            content = String(json);
+        }
+    }
+    // Truncate if needed
+    let truncated = false;
+    if (maxLength && content.length > maxLength) {
+        content = content.substring(0, maxLength) + '\n' + truncationIndicator;
+        truncated = true;
+    }
+    // Escape any backticks that might break the code block
+    content = escapeCodeBlock(content);
+    return { valid, content, truncated, error };
+}
+/**
+ * Escape special characters in inline code.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for inline code
+ */
+export function escapeInlineCode(text) {
+    // Empty string returns double backticks (minimal valid inline code)
+    if (!text)
+        return '``';
+    // Single backticks can be escaped by using double backticks
+    if (text.includes('`')) {
+        // If text contains backticks, wrap with double backticks and padding spaces.
+        // Spaces are always added for clarity and to handle edge cases where
+        // text starts/ends with backticks (CommonMark strips one padding space each side).
+        return `\`\` ${text} \`\``;
+    }
+    return `\`${text}\``;
+}
+/**
+ * Escape text for use in a Markdown link title.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for link titles
+ */
+export function escapeLinkTitle(text) {
+    if (!text)
+        return '';
+    return text
+        // Escape quotes
+        .replace(/"/g, '\\"')
+        // Escape parentheses
+        .replace(/\)/g, '\\)')
+        .replace(/\(/g, '\\(');
+}
+/**
+ * Escape text for use in a Markdown bullet list item.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for list items
+ */
+export function escapeListItem(text) {
+    if (!text)
+        return '';
+    // Handle leading characters that could be interpreted as list markers
+    let escaped = text;
+    // Leading dash, asterisk, plus (unordered list)
+    if (/^[-*+]\s/.test(escaped)) {
+        escaped = '\\' + escaped;
+    }
+    // Leading number with period (ordered list)
+    if (/^\d+\.\s/.test(escaped)) {
+        escaped = escaped.replace(/^(\d+)\./, '$1\\.');
+    }
+    // Newlines in list items
+    escaped = escaped.replace(/\r?\n/g, '  \n  ');
+    return escaped;
+}
+/**
+ * Wrap text to ensure it fits within table cell width constraints.
+ *
+ * @param text - The text to wrap
+ * @param maxWidth - Maximum width (default: 50)
+ * @returns Wrapped text with <br> for line breaks
+ */
+export function wrapTableCell(text, maxWidth = DISPLAY_LIMITS.TABLE_CELL_MAX_WIDTH) {
+    if (!text || text.length <= maxWidth) {
+        return escapeTableCell(text);
+    }
+    const words = text.split(/\s+/);
+    const lines = [];
+    let currentLine = '';
+    for (const word of words) {
+        if (currentLine.length + word.length + 1 <= maxWidth) {
+            currentLine += (currentLine ? ' ' : '') + word;
+        }
+        else {
+            if (currentLine) {
+                lines.push(currentLine);
+            }
+            currentLine = word.length > maxWidth ? word.substring(0, maxWidth) + '...' : word;
+        }
+    }
+    if (currentLine) {
+        lines.push(currentLine);
+    }
+    return escapeTableCell(lines.join('\n'));
+}
+/**
+ * Build a Markdown table from headers and rows.
+ * Automatically escapes cell content.
+ *
+ * @param headers - Array of header strings
+ * @param rows - 2D array of cell values
+ * @param alignments - Optional array of column alignments ('left', 'center', 'right')
+ * @returns Complete Markdown table string
+ */
+export function buildTable(headers, rows, alignments) {
+    const lines = [];
+    // Header row
+    const escapedHeaders = headers.map(h => escapeTableCell(h));
+    lines.push(`| ${escapedHeaders.join(' | ')} |`);
+    // Separator row with alignment
+    const separators = headers.map((_, i) => {
+        const align = alignments?.[i] ?? 'left';
+        switch (align) {
+            case 'center':
+                return ':---:';
+            case 'right':
+                return '---:';
+            default:
+                return '---';
+        }
+    });
+    lines.push(`| ${separators.join(' | ')} |`);
+    // Data rows
+    for (const row of rows) {
+        const escapedCells = row.map(cell => escapeTableCell(cell));
+        // Pad row if needed
+        while (escapedCells.length < headers.length) {
+            escapedCells.push('');
+        }
+        lines.push(`| ${escapedCells.join(' | ')} |`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=markdown.js.map