postgres-scout-mcp 1.0.0

package/dist/tools/temporal.js

@@ -0,0 +1,313 @@
+import { z } from 'zod';
+import { executeInternalQuery } from '../utils/database.js';
+import { escapeIdentifier, sanitizeIdentifier, normalizeInterval, validateOrderBy } from '../utils/sanitize.js';
+import { WhereConditionSchema, buildWhereClause } from '../utils/query-builder.js';
+const FindRecentSchema = z.object({
+    table: z.string(),
+    timestampColumn: z.string(),
+    timeWindow: z.string().describe('Time interval, e.g., "7 days", "2 hours", "30 minutes", or shorthand "7d", "2h", "30m", "1y"'),
+    schema: z.string().optional().default('public'),
+    where: z.array(WhereConditionSchema).optional(),
+    limit: z.number().optional().default(100),
+    orderBy: z.string().optional()
+});
+const AnalyzeTimeSeriesSchema = z.object({
+    table: z.string(),
+    timestampColumn: z.string(),
+    valueColumn: z.string(),
+    schema: z.string().optional().default('public'),
+    groupBy: z.enum(['hour', 'day', 'week', 'month']).optional().default('day'),
+    aggregation: z.enum(['sum', 'avg', 'count', 'min', 'max']).optional().default('sum'),
+    startDate: z.string().optional(),
+    endDate: z.string().optional(),
+    includeMovingAverage: z.boolean().optional().default(true),
+    movingAverageWindow: z.number().optional().default(7)
+});
+const DetectSeasonalitySchema = z.object({
+    table: z.string(),
+    timestampColumn: z.string(),
+    valueColumn: z.string(),
+    schema: z.string().optional().default('public'),
+    groupBy: z.enum(['day_of_week', 'day_of_month', 'month', 'quarter']).optional().default('day_of_week'),
+    minPeriods: z.number().optional().default(4)
+});
+export async function findRecent(connection, logger, args) {
+    const { table, timestampColumn, timeWindow, schema, where, limit, orderBy } = args;
+    logger.info('findRecent', 'Finding recent records', { table, timeWindow });
+    const normalizedTimeWindow = normalizeInterval(timeWindow);
+    if (orderBy) {
+        validateOrderBy(orderBy);
+    }
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const sanitizedTimestamp = sanitizeIdentifier(timestampColumn);
+    let whereClause = '';
+    let countWhereClause = '';
+    let queryParams = [limit];
+    let countParams = [];
+    if (where && where.length > 0) {
+        const built = buildWhereClause(where, 2); // $1 is limit
+        whereClause = `AND (${built.clause})`;
+        queryParams = [limit, ...built.params];
+        const countBuilt = buildWhereClause(where, 1); // no limit offset
+        countWhereClause = `AND (${countBuilt.clause})`;
+        countParams = countBuilt.params;
+    }
+    const orderClause = orderBy || `${escapeIdentifier(sanitizedTimestamp)} DESC`;
+    const query = `
+    SELECT *
+    FROM ${escapeIdentifier(sanitizedSchema)}.${escapeIdentifier(sanitizedTable)}
+    WHERE ${escapeIdentifier(sanitizedTimestamp)} >= NOW() - INTERVAL '${normalizedTimeWindow}'
+      ${whereClause}
+    ORDER BY ${orderClause}
+    LIMIT $1
+  `;
+    const countQuery = `
+    SELECT
+      COUNT(*) as rows_found,
+      NOW() - INTERVAL '${normalizedTimeWindow}' as threshold
+    FROM ${escapeIdentifier(sanitizedSchema)}.${escapeIdentifier(sanitizedTable)}
+    WHERE ${escapeIdentifier(sanitizedTimestamp)} >= NOW() - INTERVAL '${normalizedTimeWindow}'
+      ${countWhereClause}
+  `;
+    const [result, countResult] = await Promise.all([
+        executeInternalQuery(connection, logger, { query, params: queryParams }),
+        executeInternalQuery(connection, logger, { query: countQuery, params: countParams })
+    ]);
+    return {
+        table,
+        schema,
+        timestampColumn,
+        timeWindow: `Last ${normalizedTimeWindow}`,
+        threshold: countResult.rows[0]?.threshold,
+        rowsFound: parseInt(countResult.rows[0]?.rows_found || '0', 10),
+        rows: result.rows
+    };
+}
+export async function analyzeTimeSeries(connection, logger, args) {
+    const { table, timestampColumn, valueColumn, schema, groupBy, aggregation, startDate, endDate, includeMovingAverage, movingAverageWindow } = args;
+    logger.info('analyzeTimeSeries', 'Analyzing time series', { table, groupBy, aggregation });
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const sanitizedTimestamp = sanitizeIdentifier(timestampColumn);
+    const sanitizedValue = sanitizeIdentifier(valueColumn);
+    const dateGroupMap = {
+        hour: `DATE_TRUNC('hour', ${escapeIdentifier(sanitizedTimestamp)})`,
+        day: `DATE_TRUNC('day', ${escapeIdentifier(sanitizedTimestamp)})`,
+        week: `DATE_TRUNC('week', ${escapeIdentifier(sanitizedTimestamp)})`,
+        month: `DATE_TRUNC('month', ${escapeIdentifier(sanitizedTimestamp)})`
+    };
+    const aggMap = {
+        sum: `SUM(${escapeIdentifier(sanitizedValue)})`,
+        avg: `AVG(${escapeIdentifier(sanitizedValue)})`,
+        count: 'COUNT(*)',
+        min: `MIN(${escapeIdentifier(sanitizedValue)})`,
+        max: `MAX(${escapeIdentifier(sanitizedValue)})`
+    };
+    const dateFilter = [];
+    const params = [];
+    if (startDate) {
+        params.push(startDate);
+        dateFilter.push(`${escapeIdentifier(sanitizedTimestamp)} >= $${params.length}`);
+    }
+    if (endDate) {
+        params.push(endDate);
+        dateFilter.push(`${escapeIdentifier(sanitizedTimestamp)} <= $${params.length}`);
+    }
+    const whereClause = dateFilter.length > 0 ? `WHERE ${dateFilter.join(' AND ')}` : '';
+    const baseQuery = `
+    WITH time_series AS (
+      SELECT
+        ${dateGroupMap[groupBy]} as period,
+        ${aggMap[aggregation]} as value,
+        COUNT(*) as count
+      FROM ${escapeIdentifier(sanitizedSchema)}.${escapeIdentifier(sanitizedTable)}
+      ${whereClause}
+      GROUP BY ${dateGroupMap[groupBy]}
+      ORDER BY period
+    )
+    SELECT
+      period,
+      value,
+      count,
+      ${includeMovingAverage ? `
+        AVG(value) OVER (
+          ORDER BY period
+          ROWS BETWEEN ${movingAverageWindow - 1} PRECEDING AND CURRENT ROW
+        ) as moving_average,
+      ` : ''}
+      LAG(value) OVER (ORDER BY period) as previous_value,
+      CASE
+        WHEN LAG(value) OVER (ORDER BY period) IS NOT NULL AND LAG(value) OVER (ORDER BY period) != 0
+        THEN ((value - LAG(value) OVER (ORDER BY period)) / LAG(value) OVER (ORDER BY period) * 100)
+        ELSE NULL
+      END as percent_change
+    FROM time_series
+    ORDER BY period
+  `;
+    const statsQuery = `
+    SELECT
+      ${aggMap[aggregation]} as total,
+      AVG(${escapeIdentifier(sanitizedValue)}) as average,
+      PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY ${escapeIdentifier(sanitizedValue)}) as median,
+      STDDEV(${escapeIdentifier(sanitizedValue)}) as std_dev,
+      MIN(${escapeIdentifier(sanitizedValue)}) as min,
+      MAX(${escapeIdentifier(sanitizedValue)}) as max
+    FROM ${escapeIdentifier(sanitizedSchema)}.${escapeIdentifier(sanitizedTable)}
+    ${whereClause}
+  `;
+    const [timeSeriesResult, statsResult] = await Promise.all([
+        executeInternalQuery(connection, logger, { query: baseQuery, params }),
+        executeInternalQuery(connection, logger, { query: statsQuery, params })
+    ]);
+    const timeSeries = timeSeriesResult.rows.map(row => {
+        const ma = includeMovingAverage ? parseFloat(row.moving_average) : undefined;
+        const value = parseFloat(row.value);
+        let isAnomaly = false;
+        let anomalyReason = undefined;
+        if (includeMovingAverage && ma && Math.abs(value - ma) > ma * 1.5) {
+            isAnomaly = true;
+            anomalyReason = `Value is ${(value / ma).toFixed(1)}x the moving average`;
+        }
+        return {
+            period: row.period,
+            value: parseFloat(row.value),
+            count: parseInt(row.count, 10),
+            ...(includeMovingAverage && { movingAverage: ma }),
+            percentChange: row.percent_change ? parseFloat(row.percent_change).toFixed(2) : null,
+            isAnomaly,
+            ...(anomalyReason && { anomalyReason })
+        };
+    });
+    const anomalyCount = timeSeries.filter(t => t.isAnomaly).length;
+    const stats = statsResult.rows[0];
+    const statistics = {
+        total: parseFloat(stats.total || '0'),
+        average: parseFloat(stats.average || '0'),
+        median: parseFloat(stats.median || '0'),
+        stdDev: parseFloat(stats.std_dev || '0'),
+        min: parseFloat(stats.min || '0'),
+        max: parseFloat(stats.max || '0'),
+        anomalyCount
+    };
+    const recommendations = [];
+    if (anomalyCount > 0) {
+        recommendations.push(`⚠ ${anomalyCount} anomalies detected - investigate unusual spikes or drops`);
+    }
+    else {
+        recommendations.push('✓ No significant anomalies detected');
+    }
+    const avgChange = timeSeries
+        .filter(t => t.percentChange !== null)
+        .reduce((sum, t) => sum + parseFloat(t.percentChange || '0'), 0) / timeSeries.length;
+    if (avgChange > 5) {
+        recommendations.push('✓ Positive growth trend observed');
+    }
+    else if (avgChange < -5) {
+        recommendations.push('⚠ Declining trend observed');
+    }
+    else {
+        recommendations.push('✓ Stable trend');
+    }
+    return {
+        table,
+        schema,
+        period: startDate && endDate ? `${startDate} to ${endDate}` : 'All time',
+        groupBy,
+        aggregation,
+        timeSeries,
+        statistics,
+        recommendations
+    };
+}
+export async function detectSeasonality(connection, logger, args) {
+    const { table, timestampColumn, valueColumn, schema, groupBy, minPeriods } = args;
+    logger.info('detectSeasonality', 'Detecting seasonal patterns', { table, groupBy });
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const sanitizedTimestamp = sanitizeIdentifier(timestampColumn);
+    const sanitizedValue = sanitizeIdentifier(valueColumn);
+    const patternMap = {
+        day_of_week: `TO_CHAR(${escapeIdentifier(sanitizedTimestamp)}, 'Day')`,
+        day_of_month: `EXTRACT(DAY FROM ${escapeIdentifier(sanitizedTimestamp)})`,
+        month: `TO_CHAR(${escapeIdentifier(sanitizedTimestamp)}, 'Month')`,
+        quarter: `EXTRACT(QUARTER FROM ${escapeIdentifier(sanitizedTimestamp)})`
+    };
+    const query = `
+    SELECT
+      ${patternMap[groupBy]} as period,
+      AVG(${escapeIdentifier(sanitizedValue)}) as avg_value,
+      STDDEV(${escapeIdentifier(sanitizedValue)}) as std_dev,
+      COUNT(DISTINCT DATE_TRUNC('${groupBy === 'day_of_week' ? 'week' : 'month'}', ${escapeIdentifier(sanitizedTimestamp)})) as period_count,
+      MIN(${escapeIdentifier(sanitizedValue)}) as min_value,
+      MAX(${escapeIdentifier(sanitizedValue)}) as max_value
+    FROM ${escapeIdentifier(sanitizedSchema)}.${escapeIdentifier(sanitizedTable)}
+    GROUP BY ${patternMap[groupBy]}
+    HAVING COUNT(DISTINCT DATE_TRUNC('${groupBy === 'day_of_week' ? 'week' : 'month'}', ${escapeIdentifier(sanitizedTimestamp)})) >= $1
+    ORDER BY
+      CASE ${patternMap[groupBy]}
+        WHEN 'Monday' THEN 1
+        WHEN 'Tuesday' THEN 2
+        WHEN 'Wednesday' THEN 3
+        WHEN 'Thursday' THEN 4
+        WHEN 'Friday' THEN 5
+        WHEN 'Saturday' THEN 6
+        WHEN 'Sunday' THEN 7
+        ELSE ${patternMap[groupBy]}::int
+      END
+  `;
+    const result = await executeInternalQuery(connection, logger, {
+        query,
+        params: [minPeriods]
+    });
+    const patterns = result.rows.map(row => ({
+        period: typeof row.period === 'string' ? row.period.trim() : row.period,
+        avgValue: parseFloat(row.avg_value),
+        stdDev: parseFloat(row.std_dev || '0'),
+        coefficient: parseFloat(row.std_dev || '0') / parseFloat(row.avg_value || '1'),
+        minValue: parseFloat(row.min_value),
+        maxValue: parseFloat(row.max_value),
+        periodsAnalyzed: parseInt(row.period_count, 10)
+    }));
+    const insights = [];
+    if (patterns.length > 0) {
+        insights.push('✓ Seasonal pattern detected');
+        const maxPattern = patterns.reduce((max, p) => p.avgValue > max.avgValue ? p : max);
+        const minPattern = patterns.reduce((min, p) => p.avgValue < min.avgValue ? p : min);
+        insights.push(`${maxPattern.period} has highest average value (${maxPattern.avgValue.toFixed(2)})`);
+        insights.push(`${minPattern.period} has lowest average value (${minPattern.avgValue.toFixed(2)})`);
+        const avgCoefficient = patterns.reduce((sum, p) => sum + p.coefficient, 0) / patterns.length;
+        if (avgCoefficient < 0.2) {
+            insights.push('✓ Strong consistent pattern (low variance)');
+        }
+        else if (avgCoefficient > 0.5) {
+            insights.push('⚠ High variance in pattern - less predictable');
+        }
+    }
+    else {
+        insights.push('⚠ Insufficient data to detect seasonal patterns');
+    }
+    return {
+        table,
+        schema,
+        pattern: groupBy,
+        periodsAnalyzed: patterns.length > 0 ? patterns[0].periodsAnalyzed : 0,
+        patterns,
+        insights
+    };
+}
+export const temporalTools = {
+    findRecent: {
+        schema: FindRecentSchema,
+        handler: findRecent
+    },
+    analyzeTimeSeries: {
+        schema: AnalyzeTimeSeriesSchema,
+        handler: analyzeTimeSeries
+    },
+    detectSeasonality: {
+        schema: DetectSeasonalitySchema,
+        handler: detectSeasonality
+    }
+};
+//# sourceMappingURL=temporal.js.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/database.js

@@ -0,0 +1,123 @@
+import { Pool } from 'pg';
+import { sanitizeQuery, parseIntSafe } from './sanitize.js';
+import { formatError } from './result-formatter.js';
+export async function createDatabaseConnection(config, logger) {
+    const pool = new Pool({
+        connectionString: config.connectionString,
+        max: parseIntSafe(process.env.PGMAXPOOLSIZE || '10', 10),
+        min: parseIntSafe(process.env.PGMINPOOLSIZE || '2', 2),
+        idleTimeoutMillis: parseIntSafe(process.env.PGIDLETIMEOUT || '10000', 10000),
+        connectionTimeoutMillis: 5000,
+    });
+    pool.on('error', (err) => {
+        logger.error('database', 'Unexpected database error', { error: err.message });
+    });
+    try {
+        const client = await pool.connect();
+        logger.info('database', 'Database connection established');
+        client.release();
+    }
+    catch (error) {
+        logger.error('database', 'Failed to connect to database', { error: formatError(error) });
+        throw new Error(`Database connection failed: ${formatError(error)}`);
+    }
+    return { pool, config };
+}
+export async function executeQuery(connection, logger, params) {
+    const { query, params: queryParams = [], options = {} } = params;
+    const { config, pool } = connection;
+    sanitizeQuery(query, config.mode, { internal: options.internal });
+    const timeout = options.timeout || config.queryTimeout;
+    const maxRows = options.maxRows || config.maxResultRows;
+    logger.debug('query', 'Executing query', {
+        query: query.substring(0, 200),
+        params: queryParams,
+        timeout,
+        maxRows
+    });
+    let client = null;
+    const startTime = Date.now();
+    try {
+        client = await pool.connect();
+        if (!Number.isFinite(timeout) || timeout < 0) {
+            throw new Error('Invalid timeout value');
+        }
+        await client.query(`SET statement_timeout = ${Math.floor(timeout)}`);
+        const result = await client.query({
+            text: query,
+            values: queryParams
+        });
+        const executionTime = Date.now() - startTime;
+        if (result.rowCount && result.rowCount > maxRows) {
+            logger.warn('query', 'Result set exceeds max rows', {
+                rowCount: result.rowCount,
+                maxRows
+            });
+            result.rows = result.rows.slice(0, maxRows);
+            result.rowCount = maxRows;
+        }
+        logger.info('query', 'Query executed successfully', {
+            rowCount: result.rowCount,
+            executionTimeMs: executionTime
+        });
+        return result;
+    }
+    catch (error) {
+        const executionTime = Date.now() - startTime;
+        logger.error('query', 'Query execution failed', {
+            error: formatError(error),
+            executionTimeMs: executionTime,
+            query: query.substring(0, 200)
+        });
+        throw error;
+    }
+    finally {
+        if (client) {
+            client.release();
+        }
+    }
+}
+export async function executeInternalQuery(connection, logger, params) {
+    return executeQuery(connection, logger, {
+        ...params,
+        options: { ...params.options, internal: true }
+    });
+}
+export async function getCurrentDatabaseName(connection, logger) {
+    const query = 'SELECT current_database() as name';
+    const result = await executeInternalQuery(connection, logger, { query });
+    return result.rows[0]?.name || connection.pool.options.database || 'current';
+}
+export async function ensureDatabaseExists(connection, logger, database) {
+    const query = `
+    SELECT 1
+    FROM pg_catalog.pg_database
+    WHERE datname = $1
+  `;
+    const result = await executeInternalQuery(connection, logger, { query, params: [database] });
+    if (result.rowCount === 0) {
+        throw new Error(`Database "${database}" does not exist`);
+    }
+}
+export async function closeDatabaseConnection(connection, logger) {
+    try {
+        await connection.pool.end();
+        logger.info('database', 'Database connection closed');
+    }
+    catch (error) {
+        logger.error('database', 'Error closing database connection', { error: formatError(error) });
+        throw error;
+    }
+}
+export async function testConnection(pool) {
+    try {
+        const client = await pool.connect();
+        await client.query('SELECT 1');
+        client.release();
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/utils/logger.js

@@ -0,0 +1,73 @@
+import { appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { sanitizeLogValue } from './sanitize.js';
+export class Logger {
+    logDir;
+    logLevel;
+    toolLogPath;
+    errorLogPath;
+    constructor(logDir, logLevel = 'info') {
+        this.logDir = logDir;
+        this.logLevel = logLevel;
+        this.toolLogPath = join(logDir, 'tool-usage.log');
+        this.errorLogPath = join(logDir, 'error.log');
+        if (!existsSync(logDir)) {
+            mkdirSync(logDir, { recursive: true });
+        }
+    }
+    getLevelPriority(level) {
+        const priorities = { debug: 0, info: 1, warn: 2, error: 3 };
+        return priorities[level] ?? 1;
+    }
+    shouldLog(level) {
+        return this.getLevelPriority(level) >= this.getLevelPriority(this.logLevel);
+    }
+    formatLogEntry(entry) {
+        const timestamp = entry.timestamp.toISOString();
+        const safeMessage = sanitizeLogValue(entry.message);
+        const safeTool = sanitizeLogValue(entry.tool);
+        const dataStr = entry.data ? `, Data: ${sanitizeLogValue(entry.data)}` : '';
+        return `${timestamp} [${entry.level.toUpperCase()}] Tool: ${safeTool}, Message: ${safeMessage}${dataStr}\n`;
+    }
+    writeLog(filePath, content) {
+        try {
+            appendFileSync(filePath, content, 'utf8');
+        }
+        catch (error) {
+            console.error(`Failed to write to log file ${filePath}:`, error);
+        }
+    }
+    log(level, tool, message, data) {
+        if (!this.shouldLog(level))
+            return;
+        const entry = {
+            timestamp: new Date(),
+            level,
+            tool,
+            message,
+            data
+        };
+        const formatted = this.formatLogEntry(entry);
+        console.error(formatted.trim());
+        this.writeLog(this.toolLogPath, formatted);
+        if (level === 'error') {
+            this.writeLog(this.errorLogPath, formatted);
+        }
+    }
+    debug(tool, message, data) {
+        this.log('debug', tool, message, data);
+    }
+    info(tool, message, data) {
+        this.log('info', tool, message, data);
+    }
+    warn(tool, message, data) {
+        this.log('warn', tool, message, data);
+    }
+    error(tool, message, data) {
+        this.log('error', tool, message, data);
+    }
+}
+export const createLogger = (logDir, logLevel = 'info') => {
+    return new Logger(logDir, logLevel);
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/query-builder.js

@@ -0,0 +1,180 @@
+import { sanitizeIdentifier, escapeIdentifier } from './sanitize.js';
+import { z } from 'zod';
+const ComparisonOpSchema = z.enum(['=', '!=', '>', '<', '>=', '<=', 'LIKE', 'ILIKE']);
+const ComparisonConditionSchema = z.object({
+    field: z.string(),
+    op: ComparisonOpSchema,
+    value: z.union([z.string(), z.number(), z.boolean()])
+}).strict();
+const InConditionSchema = z.object({
+    field: z.string(),
+    op: z.enum(['IN', 'NOT IN']),
+    value: z.array(z.union([z.string(), z.number()])).min(1)
+}).strict();
+const NullConditionSchema = z.object({
+    field: z.string(),
+    op: z.enum(['IS NULL', 'IS NOT NULL'])
+}).strict();
+const BetweenConditionSchema = z.object({
+    field: z.string(),
+    op: z.literal('BETWEEN'),
+    value: z.tuple([z.union([z.string(), z.number()]), z.union([z.string(), z.number()])])
+}).strict();
+const LeafConditionSchema = z.union([
+    ComparisonConditionSchema,
+    InConditionSchema,
+    NullConditionSchema,
+    BetweenConditionSchema
+]);
+export const WhereConditionSchema = z.lazy(() => z.union([
+    LeafConditionSchema,
+    z.object({ and: z.array(WhereConditionSchema).min(1) }).strict(),
+    z.object({ or: z.array(WhereConditionSchema).min(1) }).strict()
+]));
+// --- Trivially-true condition detection ---
+const MAX_SAFE_BETWEEN_RANGE = 1_000_000_000; // 1 billion — any range wider than this is suspicious
+const COMPLEMENTARY_OPS = [
+    { op1: '>', op2: '<=' },
+    { op1: '>=', op2: '<' },
+    { op1: '=', op2: '!=' },
+    { op1: 'IS NULL', op2: 'IS NOT NULL' },
+];
+function checkOrGroupTriviallyTrue(conditions) {
+    const leaves = conditions.filter((c) => 'op' in c);
+    for (let i = 0; i < leaves.length; i++) {
+        for (let j = i + 1; j < leaves.length; j++) {
+            const a = leaves[i];
+            const b = leaves[j];
+            if (a.field !== b.field)
+                continue;
+            for (const pair of COMPLEMENTARY_OPS) {
+                const match = (a.op === pair.op1 && b.op === pair.op2) ||
+                    (a.op === pair.op2 && b.op === pair.op1);
+                if (!match)
+                    continue;
+                if (pair.op1 === 'IS NULL') {
+                    throw new Error(`Trivially true condition detected: OR(${a.field} IS NULL, ${a.field} IS NOT NULL) matches all rows.`);
+                }
+                if ('value' in a && 'value' in b && a.value === b.value) {
+                    throw new Error(`Trivially true condition detected: OR(${a.field} ${a.op} ${a.value}, ${b.field} ${b.op} ${b.value}) matches all rows.`);
+                }
+            }
+        }
+    }
+}
+function checkLeafTriviallyTrue(condition) {
+    if ('and' in condition) {
+        for (const c of condition.and)
+            checkLeafTriviallyTrue(c);
+        return;
+    }
+    if ('or' in condition) {
+        checkOrGroupTriviallyTrue(condition.or);
+        for (const c of condition.or)
+            checkLeafTriviallyTrue(c);
+        return;
+    }
+    // LIKE/ILIKE wildcard-only patterns (%, %%, _%, %_%, __, etc.)
+    if ((condition.op === 'LIKE' || condition.op === 'ILIKE') && 'value' in condition) {
+        const val = String(condition.value);
+        if (val.replace(/[%_]/g, '') === '') {
+            throw new Error(`Trivially true condition detected: ${condition.op} '${val}' matches all rows. Use a more specific pattern.`);
+        }
+    }
+    // BETWEEN with extreme numeric range
+    if (condition.op === 'BETWEEN' && 'value' in condition) {
+        const [low, high] = condition.value;
+        if (typeof low === 'number' && typeof high === 'number') {
+            const range = high - low;
+            if (range >= MAX_SAFE_BETWEEN_RANGE) {
+                throw new Error(`Trivially true condition detected: BETWEEN ${low} AND ${high} spans ${range.toLocaleString()} values. Use a narrower range.`);
+            }
+        }
+    }
+}
+function assertNotTriviallyTrue(conditions) {
+    // Flatten: if there's exactly one top-level condition and it's an AND group, unwrap it
+    let effective = conditions;
+    if (effective.length === 1 && 'and' in effective[0]) {
+        effective = effective[0].and;
+    }
+    // Check: sole IS NOT NULL
+    if (effective.length === 1) {
+        const c = effective[0];
+        if ('op' in c && c.op === 'IS NOT NULL') {
+            throw new Error('Trivially true condition detected: IS NOT NULL as the sole WHERE condition matches all non-null rows. Add additional conditions to narrow the scope.');
+        }
+    }
+    // Recursively check all leaf conditions for trivially-true patterns
+    for (const condition of effective) {
+        checkLeafTriviallyTrue(condition);
+    }
+}
+// --- Builder ---
+function buildCondition(condition, paramCounter, params) {
+    // AND group
+    if ('and' in condition) {
+        const parts = condition.and.map(c => buildCondition(c, paramCounter, params));
+        return parts.length === 1 ? parts[0] : `(${parts.join(' AND ')})`;
+    }
+    // OR group
+    if ('or' in condition) {
+        const parts = condition.or.map(c => buildCondition(c, paramCounter, params));
+        return parts.length === 1 ? parts[0] : `(${parts.join(' OR ')})`;
+    }
+    // Leaf condition — sanitize and escape the field name
+    const escapedField = escapeIdentifier(sanitizeIdentifier(condition.field));
+    if (condition.op === 'IS NULL') {
+        return `${escapedField} IS NULL`;
+    }
+    if (condition.op === 'IS NOT NULL') {
+        return `${escapedField} IS NOT NULL`;
+    }
+    if (condition.op === 'IN' || condition.op === 'NOT IN') {
+        if (condition.value.length === 0) {
+            throw new Error(`${condition.op} requires at least one value`);
+        }
+        const placeholders = condition.value.map(v => {
+            params.push(v);
+            return `$${paramCounter.value++}`;
+        });
+        return `${escapedField} ${condition.op} (${placeholders.join(', ')})`;
+    }
+    if (condition.op === 'BETWEEN') {
+        const p1 = `$${paramCounter.value++}`;
+        params.push(condition.value[0]);
+        const p2 = `$${paramCounter.value++}`;
+        params.push(condition.value[1]);
+        return `${escapedField} BETWEEN ${p1} AND ${p2}`;
+    }
+    // Comparison operators: =, !=, >, <, >=, <=, LIKE, ILIKE
+    const placeholder = `$${paramCounter.value++}`;
+    params.push(condition.value);
+    return `${escapedField} ${condition.op} ${placeholder}`;
+}
+export function buildWhereClause(conditions, startParam = 1) {
+    if (conditions.length === 0) {
+        return { clause: '', params: [] };
+    }
+    assertNotTriviallyTrue(conditions);
+    const params = [];
+    const paramCounter = { value: startParam };
+    const parts = conditions.map(c => buildCondition(c, paramCounter, params));
+    return {
+        clause: parts.join(' AND '),
+        params
+    };
+}
+// --- Formatting utilities (unchanged) ---
+export function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 Bytes';
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+export function formatNumber(num) {
+    return num.toLocaleString();
+}
+//# sourceMappingURL=query-builder.js.map