@anyshift/mcp-proxy 0.2.0 → 0.2.2

package/dist/__tests__/unit/truncation.test.js

@@ -0,0 +1,204 @@
+/**
+ * Unit tests for truncation module
+ * Tests token estimation and truncation logic
+ */
+import { describe, test, expect } from '@jest/globals';
+import { estimateTokens, wouldBeTruncated, truncateResponseIfNeeded } from '../../truncation/truncate.js';
+describe('Truncation - Token Estimation', () => {
+    test('estimateTokens with default ratio (4 chars/token)', () => {
+        expect(estimateTokens('x'.repeat(100))).toBe(25); // 100/4 = 25
+        expect(estimateTokens('x'.repeat(1000))).toBe(250); // 1000/4 = 250
+        expect(estimateTokens('x'.repeat(40000))).toBe(10000); // 40000/4 = 10000
+    });
+    test('estimateTokens with custom ratio', () => {
+        expect(estimateTokens('x'.repeat(100), 3)).toBe(34); // 100/3 = 33.33 -> 34 (ceil)
+        expect(estimateTokens('x'.repeat(100), 5)).toBe(20); // 100/5 = 20
+    });
+    test('estimateTokens handles empty string', () => {
+        expect(estimateTokens('')).toBe(0);
+    });
+    test('estimateTokens rounds up (ceiling)', () => {
+        expect(estimateTokens('xxx', 4)).toBe(1); // 3/4 = 0.75 -> 1
+        expect(estimateTokens('xxxxx', 4)).toBe(2); // 5/4 = 1.25 -> 2
+    });
+});
+describe('Truncation - Would Be Truncated Check', () => {
+    test('returns false when content is under limit', () => {
+        const content = 'x'.repeat(30000); // 7500 tokens
+        expect(wouldBeTruncated(content, 10000, 4)).toBe(false);
+    });
+    test('returns true when content exceeds limit', () => {
+        const content = 'x'.repeat(50000); // 12500 tokens
+        expect(wouldBeTruncated(content, 10000, 4)).toBe(true);
+    });
+    test('returns false when exactly at limit', () => {
+        const content = 'x'.repeat(40000); // exactly 10000 tokens
+        expect(wouldBeTruncated(content, 10000, 4)).toBe(false);
+    });
+    test('returns true when 1 char over limit', () => {
+        const content = 'x'.repeat(40001); // 10000.25 -> 10001 tokens
+        expect(wouldBeTruncated(content, 10000, 4)).toBe(true);
+    });
+});
+describe('Truncation - Truncate Response If Needed', () => {
+    let config;
+    beforeEach(() => {
+        config = {
+            maxTokens: 10000,
+            charsPerToken: 4,
+            enableLogging: false,
+            messagePrefix: 'RESPONSE TRUNCATED'
+        };
+    });
+    test('Does not truncate when under limit', () => {
+        const content = 'x'.repeat(30000); // 7500 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toBe(content);
+        expect(result).not.toContain('=== RESPONSE TRUNCATED ===');
+        expect(result.length).toBe(30000);
+    });
+    test('Truncates when over limit', () => {
+        const content = 'x'.repeat(100000); // 25000 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+        expect(result).toContain('Estimated tokens: 25000 (limit: 10000)');
+        expect(result).toContain('Please refine your query');
+        expect(result).toContain('=== END TRUNCATION NOTICE ===');
+    });
+    test('Truncated content is under maxChars', () => {
+        const content = 'x'.repeat(100000); // 25000 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        // Result should be truncation notice + 40000 chars of content
+        const maxChars = config.maxTokens * (config.charsPerToken || 4);
+        expect(result.length).toBeLessThan(maxChars + 500); // +500 for notice
+    });
+    test('Exactly at limit: no truncation', () => {
+        const content = 'x'.repeat(40000); // exactly 10000 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toBe(content);
+        expect(result).not.toContain('=== RESPONSE TRUNCATED ===');
+    });
+    test('One char over limit: truncates', () => {
+        const content = 'x'.repeat(40001); // 10000.25 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+    });
+    test('Custom message prefix', () => {
+        config.messagePrefix = 'CUSTOM TRUNCATION MESSAGE';
+        const content = 'x'.repeat(100000);
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== CUSTOM TRUNCATION MESSAGE ===');
+    });
+    test('Custom charsPerToken ratio', () => {
+        config.charsPerToken = 3; // Tighter ratio
+        const content = 'x'.repeat(35000); // 11666 tokens with ratio of 3
+        const result = truncateResponseIfNeeded(config, content);
+        // Should truncate (11666 > 10000)
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+        expect(result).toContain('limit: 10000');
+        // Truncated to 30000 chars (10000 * 3)
+        const truncatedContent = result.split('=== END TRUNCATION NOTICE ===')[1];
+        expect(truncatedContent.trim().length).toBeLessThanOrEqual(30000);
+    });
+    test('Truncation preserves original content up to limit', () => {
+        const content = 'ABCD'.repeat(25000); // 100000 chars, 25000 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        // After truncation notice, should have first 40000 chars
+        const truncatedContent = result.split('=== END TRUNCATION NOTICE ===\n\n')[1];
+        expect(truncatedContent).toBe('ABCD'.repeat(10000)); // 40000 chars
+    });
+    test('Small content is not affected', () => {
+        const content = 'Hello, world!';
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toBe(content);
+    });
+    test('Empty content is not affected', () => {
+        const content = '';
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toBe('');
+    });
+});
+describe('Truncation - Edge Cases', () => {
+    let config;
+    beforeEach(() => {
+        config = {
+            maxTokens: 10000,
+            charsPerToken: 4,
+            enableLogging: false,
+            messagePrefix: 'RESPONSE TRUNCATED'
+        };
+    });
+    test('Handles very large content', () => {
+        const content = 'x'.repeat(1000000); // 1 million chars
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+        expect(result).toContain('Estimated tokens: 250000');
+        expect(result.length).toBeLessThan(50000); // Truncated + notice
+    });
+    test('Handles special characters', () => {
+        const content = '🚀'.repeat(25000); // Emoji might be 2 chars each in JS
+        const result = truncateResponseIfNeeded(config, content);
+        // Should still apply truncation logic based on string length
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+    });
+    test('Handles newlines and whitespace', () => {
+        const content = 'line\n'.repeat(20000); // 100000 chars with newlines
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+    });
+    test('Truncation notice format is consistent', () => {
+        const content = 'x'.repeat(100000);
+        const result = truncateResponseIfNeeded(config, content);
+        // Verify notice structure
+        expect(result).toMatch(/=== RESPONSE TRUNCATED ===/);
+        expect(result).toMatch(/Estimated tokens: \d+ \(limit: \d+\)/);
+        expect(result).toMatch(/Response truncated to prevent context overflow\./);
+        expect(result).toMatch(/=== END TRUNCATION NOTICE ===/);
+        // Notice should be at the beginning
+        expect(result.indexOf('=== RESPONSE TRUNCATED ===')).toBe(0);
+    });
+});
+describe('Truncation - Different Token Limits', () => {
+    test('5000 token limit', () => {
+        const config = {
+            maxTokens: 5000,
+            charsPerToken: 4,
+            enableLogging: false
+        };
+        const content = 'x'.repeat(30000); // 7500 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+        expect(result).toContain('limit: 5000');
+        // Should truncate to 20000 chars (5000 * 4)
+        const truncatedContent = result.split('=== END TRUNCATION NOTICE ===\n\n')[1];
+        expect(truncatedContent.length).toBe(20000);
+    });
+    test('20000 token limit', () => {
+        const config = {
+            maxTokens: 20000,
+            charsPerToken: 4,
+            enableLogging: false
+        };
+        const content = 'x'.repeat(100000); // 25000 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+        expect(result).toContain('limit: 20000');
+        // Should truncate to 80000 chars (20000 * 4)
+        const truncatedContent = result.split('=== END TRUNCATION NOTICE ===\n\n')[1];
+        expect(truncatedContent.length).toBe(80000);
+    });
+    test('Very low token limit (100)', () => {
+        const config = {
+            maxTokens: 100,
+            charsPerToken: 4,
+            enableLogging: false
+        };
+        const content = 'x'.repeat(1000); // 250 tokens
+        const result = truncateResponseIfNeeded(config, content);
+        expect(result).toContain('=== RESPONSE TRUNCATED ===');
+        expect(result).toContain('limit: 100');
+        // Should truncate to 400 chars (100 * 4)
+        const truncatedContent = result.split('=== END TRUNCATION NOTICE ===\n\n')[1];
+        expect(truncatedContent.length).toBe(400);
+    });
+});

package/dist/fileWriter/index.d.ts

@@ -15,4 +15,4 @@ export declare function createFileWriter(config: FileWriterConfig): {
     handleResponse: (toolName: string, args: Record<string, unknown>, responseData: unknown) => Promise<FileWriterResult | unknown>;
 };
 export type { FileWriterConfig, FileWriterResult } from './types.js';
-export { analyzeJsonSchema, extractNullableFields } from './schema.js';
+export { generateQueryAssistSchema } from './schema.js';

package/dist/fileWriter/index.js

@@ -18,4 +18,4 @@ export function createFileWriter(config) {
         },
     };
 }
-export { analyzeJsonSchema, extractNullableFields } from './schema.js';
+export { generateQueryAssistSchema } from './schema.js';

package/dist/fileWriter/schema.d.ts

@@ -1,15 +1,42 @@
-import { JsonSchema, NullableFields } from '../types/index.js';
 /**
- * Analyze JSON structure and generate enhanced schema
- * @param obj - The object to analyze
- * @param path - Current path in the object (for debugging)
- * @returns Schema representation of the object
+ * Query-Assist Schema Generator
+ *
+ * Generates compact, LLM-friendly schemas optimized for crafting JQ queries.
+ * Uses JQ-style path notation (.items[].price) instead of JSON Schema.
+ * Includes exploration prompts when limits are reached.
  */
-export declare function analyzeJsonSchema(obj: unknown, path?: string): JsonSchema;
+export interface PathInfo {
+    path: string;
+    type: string;
+    depth: number;
+    nullable?: boolean;
+    arrayLength?: number;
+    keyCount?: number;
+    mixed?: boolean;
+}
+export interface LimitMetadata {
+    depthLimitHit: boolean;
+    keyLimitHit: boolean;
+    pathLimitHit: boolean;
+    mixedSchemasDetected: boolean;
+    maxDepth: number;
+    maxKeys: number;
+    maxPaths: number;
+    totalPathsFound: number;
+    deepestPathTruncated?: string;
+    truncatedKeyCount?: number;
+}
+export interface QueryAssistOptions {
+    maxDepth?: number;
+    maxPaths?: number;
+    maxKeys?: number;
+    dataSize?: number;
+}
 /**
- * Extract nullable and always-null fields from schema
- * @param schema - The schema to analyze
- * @param basePath - Base path for field names
- * @returns Object containing arrays of always-null and nullable field paths
+ * Generate query-assist schema for JSON data
+ * Main entry point for schema generation
+ * @param data - JSON data to analyze
+ * @param options - Configuration options
+ * @returns Compact text schema optimized for JQ queries
  */
-export declare function extractNullableFields(schema: unknown, basePath?: string): NullableFields;
+export declare function generateQueryAssistSchema(data: unknown, options?: QueryAssistOptions): string;

package/dist/fileWriter/schema.js

@@ -1,120 +1,270 @@
 /**
- * Analyze JSON structure and generate enhanced schema
- * @param obj - The object to analyze
- * @param path - Current path in the object (for debugging)
- * @returns Schema representation of the object
+ * Query-Assist Schema Generator
+ *
+ * Generates compact, LLM-friendly schemas optimized for crafting JQ queries.
+ * Uses JQ-style path notation (.items[].price) instead of JSON Schema.
+ * Includes exploration prompts when limits are reached.
  */
-export function analyzeJsonSchema(obj, path = 'root') {
-    if (obj === null)
-        return { type: 'null' };
-    if (obj === undefined)
-        return { type: 'undefined' };
-    const type = Array.isArray(obj) ? 'array' : typeof obj;
-    if (type === 'object') {
-        const properties = {};
-        const objRecord = obj;
-        const keys = Object.keys(objRecord);
-        // Detect numeric string keys (common in Cypher results)
-        const numericKeys = keys.filter((k) => /^\d+$/.test(k));
-        const hasNumericKeys = keys.length > 0 && numericKeys.length >= keys.length * 0.8;
-        for (const key in objRecord) {
-            if (Object.prototype.hasOwnProperty.call(objRecord, key)) {
-                properties[key] = analyzeJsonSchema(objRecord[key], `${path}.${key}`);
+/**
+ * Collect all paths from JSON data with limits applied
+ * @param data - The JSON data to analyze
+ * @param maxDepth - Maximum depth to traverse (default: 2)
+ * @param maxKeys - Maximum keys to analyze per object (default: 50)
+ * @returns Array of path information and limit metadata
+ */
+function collectPaths(data, maxDepth = 2, maxKeys = 50) {
+    const paths = [];
+    const limits = {
+        depthLimitHit: false,
+        keyLimitHit: false,
+        pathLimitHit: false,
+        mixedSchemasDetected: false,
+        maxDepth,
+        maxKeys,
+        maxPaths: 0, // Will be set later
+        totalPathsFound: 0
+    };
+    function traverse(val, path, depth) {
+        // Hard stop at max depth
+        if (depth > maxDepth) {
+            limits.depthLimitHit = true;
+            if (!limits.deepestPathTruncated) {
+                limits.deepestPathTruncated = path;
             }
+            return;
         }
-        const schema = { type: 'object', properties };
-        // Add metadata hints for numeric keys
-        if (hasNumericKeys) {
-            schema._keysAreNumeric = true;
-            schema._accessPattern = 'Use .["0"] not .[0]';
+        if (val === null) {
+            paths.push({ path, type: 'null', depth, nullable: true });
         }
-        return schema;
-    }
-    else if (type === 'array') {
-        const arr = obj;
-        if (arr.length === 0) {
-            return { type: 'array', items: { type: 'unknown' }, length: 0 };
+        else if (Array.isArray(val)) {
+            paths.push({ path, type: 'array', depth, arrayLength: val.length });
+            if (val.length === 0) {
+                return; // Empty array, nothing to explore
+            }
+            // Sample first 5 items to detect schema variance
+            const sample = val.slice(0, Math.min(5, val.length));
+            const types = new Set(sample.map(item => item === null
+                ? 'null'
+                : Array.isArray(item)
+                    ? 'array'
+                    : typeof item));
+            // Detect mixed schemas (heterogeneous arrays)
+            // Mixed if we have more than 1 distinct type
+            const mixed = types.size > 1;
+            if (mixed) {
+                limits.mixedSchemasDetected = true;
+            }
+            // Traverse first non-null item
+            const first = sample.find(v => v !== null);
+            if (first !== undefined) {
+                const arrayPath = `${path}[]`;
+                if (mixed) {
+                    // For mixed arrays, only show the mixed marker (don't traverse to avoid duplicate paths)
+                    paths.push({ path: arrayPath, type: 'mixed', depth: depth + 1, mixed: true });
+                }
+                else {
+                    // For uniform arrays, traverse to show the structure
+                    traverse(first, arrayPath, depth + 1);
+                }
+            }
+            // For objects in arrays, also check if they have different keys
+            if (types.has('object')) {
+                const objects = sample.filter(v => v && typeof v === 'object' && !Array.isArray(v));
+                if (objects.length >= 2) {
+                    const keySets = objects.map(o => new Set(Object.keys(o)));
+                    // Check if any two objects have different keys
+                    for (let i = 0; i < keySets.length - 1; i++) {
+                        const keys1 = Array.from(keySets[i]);
+                        const keys2 = Array.from(keySets[i + 1]);
+                        if (keys1.length !== keys2.length || !keys1.every(k => keySets[i + 1].has(k))) {
+                            limits.mixedSchemasDetected = true;
+                            break;
+                        }
+                    }
+                }
+            }
         }
-        // Analyze array items for mixed types and nulls
-        const itemTypes = new Set();
-        let hasNulls = false;
-        // Sample first 10 items to detect type variance
-        const sampled = arr.slice(0, Math.min(10, arr.length));
-        for (const item of sampled) {
-            if (item === null) {
-                hasNulls = true;
-                itemTypes.add('null');
+        else if (typeof val === 'object') {
+            const keys = Object.keys(val).sort();
+            // Check for numeric keys (common pattern - treat as collection like arrays)
+            const numericKeys = keys.filter(k => /^\d+$/.test(k));
+            const hasNumericKeys = keys.length > 0 && numericKeys.length >= keys.length * 0.8;
+            // Always show key count (including 0)
+            paths.push({
+                path,
+                type: hasNumericKeys ? 'object (numeric keys)' : 'object',
+                depth,
+                keyCount: keys.length
+            });
+            if (hasNumericKeys) {
+                // Treat as collection - show ONE representative item structure
+                // This avoids enumerating .0, .1, .2, ... which is repetitive and wastes space
+                const representativePath = path ? `${path}.[<idx>]` : `.[<idx>]`;
+                // Pick first key to show structure
+                if (keys.length > 0) {
+                    const firstKey = keys[0];
+                    traverse(val[firstKey], representativePath, depth + 1);
+                }
             }
             else {
-                itemTypes.add(Array.isArray(item) ? 'array' : typeof item);
+                // Normal object - traverse keys individually
+                const keysToAnalyze = keys.slice(0, maxKeys);
+                if (keys.length > maxKeys) {
+                    limits.keyLimitHit = true;
+                    limits.truncatedKeyCount = keys.length - maxKeys;
+                }
+                // Traverse child keys
+                for (const key of keysToAnalyze) {
+                    const childPath = path ? `${path}.${key}` : `.${key}`;
+                    traverse(val[key], childPath, depth + 1);
+                }
             }
         }
-        const schema = {
-            type: 'array',
-            items: itemTypes.size === 1 && !hasNulls
-                ? analyzeJsonSchema(arr[0], `${path}[0]`)
-                : { types: Array.from(itemTypes) },
-            length: arr.length,
-        };
-        // Add hints for null handling
-        if (hasNulls) {
-            schema._hasNulls = true;
+        else {
+            // Primitive types
+            paths.push({ path, type: typeof val, depth });
         }
-        return schema;
-    }
-    else {
-        return { type };
     }
+    traverse(data, '', 0);
+    limits.totalPathsFound = paths.length;
+    return { paths, limits };
 }
 /**
- * Extract nullable and always-null fields from schema
- * @param schema - The schema to analyze
- * @param basePath - Base path for field names
- * @returns Object containing arrays of always-null and nullable field paths
+ * Select top N most relevant paths using scoring
+ * @param paths - All collected paths
+ * @param maxPaths - Maximum paths to return
+ * @returns Prioritized subset of paths
  */
-export function extractNullableFields(schema, basePath = '') {
-    const alwaysNull = [];
-    const nullable = [];
-    function traverse(s, path) {
-        if (!s || typeof s !== 'object')
-            return;
-        const schemaObj = s;
-        // Check if this field is always null
-        if (schemaObj.type === 'null') {
-            alwaysNull.push(path);
-            return;
-        }
-        // Check if this field can be null (mixed types)
-        if (schemaObj.items && typeof schemaObj.items === 'object') {
-            const items = schemaObj.items;
-            if (items.types &&
-                Array.isArray(items.types) &&
-                items.types.includes('null')) {
-                nullable.push(path);
+function selectTopPaths(paths, maxPaths) {
+    // Score each path based on relevance
+    const scored = paths.map(p => ({
+        ...p,
+        score: (p.nullable ? 0 : 10) + // Non-null = higher priority
+            (3 - p.depth) * 5 + // Shallower = higher priority
+            (p.type === 'array' ? 5 : 0) + // Arrays = interesting
+            (p.type === 'object' || p.type === 'object (numeric keys)' ? 3 : 0) + // Objects = interesting
+            (p.mixed ? 2 : 0) // Mixed types = interesting
+    }));
+    // Sort by score (desc), then by path length (asc) for stability
+    return scored
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.path.length - b.path.length;
+    })
+        .slice(0, maxPaths);
+}
+/**
+ * Format paths as query-assist text with exploration prompts
+ * @param paths - Selected paths to display
+ * @param limits - Limit metadata for generating prompts
+ * @param dataSize - Size of original data in characters
+ * @returns Formatted text schema
+ */
+function formatQueryAssist(paths, limits, dataSize) {
+    let output = '📊 STRUCTURE GUIDE (for JQ queries)\n\n';
+    output += `Size: ${dataSize.toLocaleString()} characters\n\n`;
+    // Group paths by depth
+    const byDepth = {};
+    for (const p of paths) {
+        if (!byDepth[p.depth])
+            byDepth[p.depth] = [];
+        byDepth[p.depth].push(p);
+    }
+    // Format paths by depth levels
+    const depths = Object.keys(byDepth)
+        .map(Number)
+        .sort((a, b) => a - b);
+    for (const depth of depths) {
+        const depthPaths = byDepth[depth];
+        const label = depth === 0 ? 'ROOT' : depth === 1 ? 'TOP-LEVEL' : `NESTED (depth ${depth})`;
+        output += `${label}:\n`;
+        for (const p of depthPaths) {
+            const pathStr = p.path || '(root)';
+            output += `  ${pathStr.padEnd(35)}`;
+            output += ` → ${p.type}`;
+            if (p.arrayLength !== undefined) {
+                output += `[${p.arrayLength}]`;
             }
-        }
-        // Recurse into object properties
-        if (schemaObj.type === 'object' && schemaObj.properties) {
-            const props = schemaObj.properties;
-            for (const [key, value] of Object.entries(props)) {
-                const newPath = path ? `${path}.${key}` : key;
-                traverse(value, newPath);
+            if (p.keyCount !== undefined) {
+                output += ` (${p.keyCount} keys)`;
             }
+            if (p.nullable) {
+                output += ' (nullable)';
+            }
+            if (p.mixed) {
+                output += ' ⚠️ MIXED SCHEMAS';
+            }
+            if (depth === limits.maxDepth && (p.type === 'object' || p.type === 'object (numeric keys)' || p.type === 'array')) {
+                output += ' ⚠️ DEPTH LIMIT';
+            }
+            output += '\n';
         }
-        // Recurse into array items
-        if (schemaObj.type === 'array' &&
-            schemaObj.items &&
-            typeof schemaObj.items === 'object') {
-            const items = schemaObj.items;
-            if (items.type === 'object' && items.properties) {
-                const props = items.properties;
-                for (const [key, value] of Object.entries(props)) {
-                    const newPath = path ? `${path}[].${key}` : `[].${key}`;
-                    traverse(value, newPath);
-                }
+        output += '\n';
+    }
+    // Check if we have numeric-keyed objects in the output
+    const hasNumericKeys = paths.some(p => p.path.includes('.[<idx>]'));
+    // Build exploration guide if any limits were hit or special patterns detected
+    const hasLimits = limits.depthLimitHit || limits.keyLimitHit || limits.pathLimitHit || limits.mixedSchemasDetected;
+    if (hasNumericKeys || hasLimits) {
+        output += '💡 EXPLORATION GUIDE\n\n';
+        // Numeric keys note (data-specific, keep separate)
+        if (hasNumericKeys) {
+            output += 'NUMERIC KEYS: .[<idx>] represents structure shared by all numeric keys\n';
+            output += '  Access: .["0"], .["1"] or .[0], .[1] (array-style) | List: keys\n\n';
+        }
+        // Show which limits were hit
+        if (hasLimits) {
+            const limitWarnings = [];
+            if (limits.depthLimitHit) {
+                limitWarnings.push(`DEPTH (max: ${limits.maxDepth})`);
+            }
+            if (limits.keyLimitHit && limits.truncatedKeyCount) {
+                limitWarnings.push(`KEYS (${limits.maxKeys} shown, ${limits.truncatedKeyCount} more)`);
+            }
+            if (limits.pathLimitHit) {
+                limitWarnings.push(`PATHS (${limits.maxPaths} of ${limits.totalPathsFound})`);
+            }
+            if (limits.mixedSchemasDetected) {
+                limitWarnings.push('MIXED SCHEMAS');
             }
+            output += `⚠️  Limits: ${limitWarnings.join(' | ')}\n\n`;
+            // Generic JQ exploration patterns
+            output += 'Common JQ patterns:\n';
+            output += '  • View keys:        <path> | keys\n';
+            output += '  • Check type:       <path> | type\n';
+            output += '  • Count items:      <path> | length\n';
+            output += '  • Search keys:      keys | map(select(contains("term")))\n';
+            output += '  • List all paths:   paths(scalars) | map(join("."))\n';
+            output += '  • Filter arrays:    .[] | select(type == "object")\n';
+            if (limits.mixedSchemasDetected) {
+                output += '  • Check variance:   .[] | type  or  [:3] | map(keys)\n';
+            }
+            output += '\n';
         }
     }
-    traverse(schema, basePath);
-    return { alwaysNull, nullable };
+    return output;
+}
+/**
+ * Generate query-assist schema for JSON data
+ * Main entry point for schema generation
+ * @param data - JSON data to analyze
+ * @param options - Configuration options
+ * @returns Compact text schema optimized for JQ queries
+ */
+export function generateQueryAssistSchema(data, options = {}) {
+    const maxDepth = options.maxDepth ?? 2;
+    const maxPaths = options.maxPaths ?? 20;
+    const maxKeys = options.maxKeys ?? 50;
+    // Collect paths with limits
+    const { paths, limits } = collectPaths(data, maxDepth, maxKeys);
+    // Select top paths
+    const selectedPaths = selectTopPaths(paths, maxPaths);
+    // Update limit metadata
+    limits.maxPaths = maxPaths;
+    limits.pathLimitHit = paths.length > maxPaths;
+    // Calculate data size (use provided size if available to avoid re-stringifying)
+    const dataSize = options.dataSize ?? JSON.stringify(data).length;
+    // Format as text
+    return formatQueryAssist(selectedPaths, limits, dataSize);
 }