@outsidedata/dolex 0.1.0

package/dist/src/patterns/utils.js

@@ -0,0 +1,353 @@
+/**
+ * Shared utilities for data shape analysis.
+ * Used by the pattern selector to evaluate data characteristics
+ * before scoring patterns.
+ */
+// ─── DATA SHAPE DETECTION ────────────────────────────────────────────────────
+/**
+ * Detect whether numeric data contains a time-series column.
+ * Checks column type and name heuristics.
+ */
+export function hasTimeSeriesColumn(columns) {
+    return columns.some((col) => col.type === 'date' ||
+        /^(date|time|timestamp|year|month|day|quarter|week|period|created|updated)$/i.test(col.name) ||
+        /_(date|time|at|on)$/i.test(col.name));
+}
+/**
+ * Count unique categorical values in the data for a given column name.
+ */
+export function countCategories(data, columnName) {
+    const unique = new Set();
+    for (const row of data) {
+        const val = row[columnName];
+        if (val != null) {
+            unique.add(String(val));
+        }
+    }
+    return unique.size;
+}
+/**
+ * Count unique series values in the data.
+ * A "series" column is typically the second categorical column used for grouping.
+ */
+export function countSeries(data, columns) {
+    const categoricalCols = columns.filter((c) => c.type === 'categorical');
+    if (categoricalCols.length < 2)
+        return 1;
+    // The second categorical column is typically the series
+    return countCategories(data, categoricalCols[1].name);
+}
+/**
+ * Check if any numeric column contains negative values.
+ */
+export function hasNegativeValues(data, columns) {
+    const numericCols = columns.filter((c) => c.type === 'numeric');
+    for (const col of numericCols) {
+        for (const row of data) {
+            const val = Number(row[col.name]);
+            if (!isNaN(val) && val < 0)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the min and max values across all numeric columns.
+ */
+export function getValueRange(data, columns) {
+    let min = Infinity;
+    let max = -Infinity;
+    const numericCols = columns.filter((c) => c.type === 'numeric');
+    for (const col of numericCols) {
+        for (const row of data) {
+            const val = Number(row[col.name]);
+            if (!isNaN(val)) {
+                if (val < min)
+                    min = val;
+                if (val > max)
+                    max = val;
+            }
+        }
+    }
+    if (min === Infinity)
+        min = 0;
+    if (max === -Infinity)
+        max = 0;
+    return { min, max };
+}
+/**
+ * Detect hierarchical structure in the data.
+ * Looks for parent-child relationships or multiple categorical columns
+ * with decreasing cardinality (e.g., region > country > city).
+ */
+export function detectHierarchy(data, columns) {
+    const categoricalCols = columns.filter((c) => c.type === 'categorical');
+    if (categoricalCols.length < 2)
+        return false;
+    // Check for decreasing cardinality pattern
+    const cardinalities = categoricalCols.map((col) => countCategories(data, col.name));
+    for (let i = 0; i < cardinalities.length - 1; i++) {
+        if (cardinalities[i] < cardinalities[i + 1]) {
+            // Higher level has fewer categories — possible hierarchy
+            return true;
+        }
+    }
+    // Check for parent-child naming patterns
+    const names = categoricalCols.map((c) => c.name.toLowerCase());
+    const hierarchyPairs = [
+        ['region', 'country'],
+        ['country', 'city'],
+        ['department', 'team'],
+        ['category', 'subcategory'],
+        ['parent', 'child'],
+        ['group', 'subgroup'],
+    ];
+    for (const [parent, child] of hierarchyPairs) {
+        if (names.some((n) => n.includes(parent)) && names.some((n) => n.includes(child))) {
+            return true;
+        }
+    }
+    return false;
+}
+const INTENT_KEYWORDS = {
+    comparison: [
+        /\bcompar/i,
+        /\bvs\.?\b/i,
+        /\bversus\b/i,
+        /\bbetween\b/i,
+        /\bdifference/i,
+        /\brank/i,
+        /\btop\b/i,
+        /\bbottom\b/i,
+        /\blargest\b/i,
+        /\bsmallest\b/i,
+        /\bhighest\b/i,
+        /\blowest\b/i,
+        /\bmore than\b/i,
+        /\bless than\b/i,
+        /\bgrowth\b/i,
+        /\bdecline\b/i,
+        /\bchange\b/i,
+    ],
+    distribution: [
+        /\bdistribut/i,
+        /\bspread\b/i,
+        /\boutlier/i,
+        /\bfrequenc/i,
+        /\bhistogram\b/i,
+        /\bdensity\b/i,
+        /\brange\b/i,
+        /\bvariance\b/i,
+        /\bskew/i,
+        /\bnormal\b/i,
+        /\bbell curve\b/i,
+        /\bquartile/i,
+        /\bpercentile/i,
+        /\bmedian\b/i,
+    ],
+    composition: [
+        /\bpercentage/i,
+        /\bproportion/i,
+        /\bshare\b/i,
+        /\bpart.of/i,
+        /\bmakeup\b/i,
+        /\bcompos/i,
+        /\bbreakdown\b/i,
+        /\bconstituent/i,
+        /\bsplit\b/i,
+        /\b(what|how)\s+(much|many)\s+of\b/i,
+        /\bpie\b/i,
+        /\bfraction/i,
+        /\bratio\b/i,
+        /\bpercent\b/i,
+    ],
+    time: [
+        /\bover time\b/i,
+        /\btrend/i,
+        /\btime.?series\b/i,
+        /\bmonth/i,
+        /\byear/i,
+        /\bquarter/i,
+        /\bweek/i,
+        /\bdaily\b/i,
+        /\bseason/i,
+        /\bhistor/i,
+        /\bforecast/i,
+        /\bgrowth\b/i,
+        /\bprogress/i,
+        /\bevolution\b/i,
+        /\btrajectory/i,
+    ],
+    relationship: [
+        /\bcorrelat/i,
+        /\brelation/i,
+        /\bassociat/i,
+        /\bscatter/i,
+        /\bregress/i,
+        /\bpredict/i,
+        /\bfactor/i,
+        /\binfluence/i,
+        /\bimpact\b/i,
+        /\baffect/i,
+        /\bdepend/i,
+        /\bmultivariat/i,
+        /\bdimension/i,
+        /\bprofile\b/i,
+    ],
+    flow: [
+        /\bflow\b/i,
+        /\bsankey\b/i,
+        /\btransition/i,
+        /\bconver/i,
+        /\bfunnel\b/i,
+        /\bpath\b/i,
+        /\bjourney\b/i,
+        /\bpipeline\b/i,
+        /\bstage/i,
+        /\bstep/i,
+        /\bfrom.+to\b/i,
+        /\bsource.+target\b/i,
+        /\binput.+output\b/i,
+    ],
+    unknown: [],
+};
+/**
+ * Parse user intent string and return the most likely category.
+ * Returns all matching categories ranked by keyword match count.
+ */
+export function parseIntent(intent) {
+    const scores = {
+        comparison: 0,
+        distribution: 0,
+        composition: 0,
+        time: 0,
+        relationship: 0,
+        flow: 0,
+        unknown: 0,
+    };
+    for (const [category, patterns] of Object.entries(INTENT_KEYWORDS)) {
+        if (category === 'unknown')
+            continue;
+        for (const pattern of patterns) {
+            if (pattern.test(intent)) {
+                scores[category]++;
+            }
+        }
+    }
+    let primary = 'unknown';
+    let maxScore = 0;
+    for (const [category, score] of Object.entries(scores)) {
+        if (category === 'unknown')
+            continue;
+        if (score > maxScore) {
+            maxScore = score;
+            primary = category;
+        }
+    }
+    return { primary, scores };
+}
+// ─── DATA SHAPE BUILDING ─────────────────────────────────────────────────────
+/**
+ * Build a complete PatternMatchContext from raw data, columns, and intent.
+ * This is the main entry point for constructing the context object
+ * that pattern selection rules evaluate against.
+ */
+export function buildMatchContext(data, columns, intent) {
+    const categoricalCols = columns.filter((c) => c.type === 'categorical');
+    const numericCols = columns.filter((c) => c.type === 'numeric');
+    const dateCols = columns.filter((c) => c.type === 'date');
+    const categoryCount = categoricalCols.length > 0
+        ? countCategories(data, categoricalCols[0].name)
+        : 0;
+    const seriesCount = countSeries(data, columns);
+    const valueRange = getValueRange(data, columns);
+    return {
+        data,
+        columns,
+        intent,
+        dataShape: {
+            rowCount: data.length,
+            categoryCount,
+            seriesCount,
+            numericColumnCount: numericCols.length,
+            categoricalColumnCount: categoricalCols.length,
+            dateColumnCount: dateCols.length,
+            hasTimeSeries: hasTimeSeriesColumn(columns),
+            hasHierarchy: detectHierarchy(data, columns),
+            hasNegativeValues: hasNegativeValues(data, columns),
+            valueRange,
+        },
+    };
+}
+// ─── COLUMN UTILITIES ─────────────────────────────────────────────────────────
+/**
+ * Find the first column of a given type from a list of column names
+ * using the full DataColumn metadata.
+ */
+export function findColumnByType(columns, type) {
+    return columns.find((c) => c.type === type);
+}
+/**
+ * Find all columns of a given type.
+ */
+export function findColumnsByType(columns, type) {
+    return columns.filter((c) => c.type === type);
+}
+/**
+ * Infer the Vega-Lite field type from a DataColumn type.
+ */
+export function inferFieldType(colType) {
+    switch (colType) {
+        case 'numeric':
+            return 'quantitative';
+        case 'date':
+            return 'temporal';
+        case 'categorical':
+            return 'nominal';
+        case 'id':
+            return 'nominal';
+        case 'text':
+            return 'nominal';
+        default:
+            return 'nominal';
+    }
+}
+/**
+ * Given an array of column names and full DataColumn metadata,
+ * determine the best x, y, color, and size columns.
+ * A best-effort heuristic for generateSpec functions.
+ */
+export function inferEncoding(columnNames, columns) {
+    const colMap = new Map(columns.map((c) => [c.name, c]));
+    const available = columnNames.filter((n) => colMap.has(n));
+    const categoricalCols = available.filter((n) => {
+        const c = colMap.get(n);
+        return c.type === 'categorical' || c.type === 'id' || c.type === 'text';
+    });
+    const numericCols = available.filter((n) => colMap.get(n).type === 'numeric');
+    const dateCols = available.filter((n) => colMap.get(n).type === 'date');
+    let x = null;
+    let y = null;
+    let color = null;
+    let size = null;
+    // Prefer date for x-axis if present
+    if (dateCols.length > 0) {
+        x = dateCols[0];
+    }
+    else if (categoricalCols.length > 0) {
+        x = categoricalCols[0];
+    }
+    // First numeric for y-axis
+    if (numericCols.length > 0) {
+        y = numericCols[0];
+    }
+    // Second categorical for color, or second numeric for size
+    if (categoricalCols.length > 1) {
+        color = categoricalCols.find((n) => n !== x) ?? null;
+    }
+    if (numericCols.length > 1) {
+        size = numericCols.find((n) => n !== y) ?? null;
+    }
+    return { x, y, color, size };
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/patterns/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/patterns/utils.ts"],"names":[],"mappings":"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"}

package/dist/src/query-engine/candidate-matcher.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Candidate Matcher — Fuzzy-match user query to candidate columns.
+ *
+ * Extracted from findCandidateColumns() and extractFilterHints() in the POC.
+ * No LLM calls — pure code-based scoring and filtering.
+ */
+import type { DataSchema, DataColumn } from '../types.js';
+/**
+ * Detect likely filter values in the query: proper nouns, years, quoted strings.
+ */
+export declare function extractFilterHints(query: string): string[];
+/**
+ * Find candidate columns from the schema that are relevant to the user's query.
+ *
+ * Scores columns by:
+ * - Direct column name match
+ * - Table name match
+ * - Sample value match (important for filtering)
+ * - Partial match
+ * - Filter hint matching (proper nouns, years)
+ * - Column type bonuses
+ *
+ * Also pulls in related columns from tables connected via foreign keys
+ * when filter values are found.
+ *
+ * Returns top candidates (up to ~25-30), ensuring a mix of categoricals and numerics.
+ */
+export declare function findCandidateColumns(query: string, schema: DataSchema): Array<DataColumn & {
+    table: string;
+}>;
+//# sourceMappingURL=candidate-matcher.d.ts.map

package/dist/src/query-engine/candidate-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-matcher.d.ts","sourceRoot":"","sources":["../../../src/query-engine/candidate-matcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAa,UAAU,EAAc,MAAM,aAAa,CAAC;AAEjF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA6B1D;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,GACjB,KAAK,CAAC,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoGvC"}

package/dist/src/query-engine/candidate-matcher.js

@@ -0,0 +1,157 @@
+/**
+ * Candidate Matcher — Fuzzy-match user query to candidate columns.
+ *
+ * Extracted from findCandidateColumns() and extractFilterHints() in the POC.
+ * No LLM calls — pure code-based scoring and filtering.
+ */
+/**
+ * Detect likely filter values in the query: proper nouns, years, quoted strings.
+ */
+export function extractFilterHints(query) {
+    const hints = [];
+    // Capitalized words that aren't at sentence start (proper nouns: "Hamilton", "Ferrari", "Monaco")
+    const words = query.split(/\s+/);
+    for (let i = 1; i < words.length; i++) {
+        const clean = words[i].replace(/[^a-zA-Z0-9]/g, '');
+        if (clean.length >= 3 && clean[0] === clean[0].toUpperCase() && clean[0] !== clean[0].toLowerCase()) {
+            hints.push(clean.toLowerCase());
+        }
+    }
+    // Also check first word if it looks like a proper noun (not common words)
+    const commonStarters = new Set([
+        'show', 'how', 'what', 'which', 'top', 'total', 'average', 'number',
+        'count', 'list', 'compare', 'get', 'find',
+    ]);
+    if (words[0] && !commonStarters.has(words[0].toLowerCase())) {
+        const clean = words[0].replace(/[^a-zA-Z0-9]/g, '');
+        if (clean.length >= 3 && clean[0] === clean[0].toUpperCase()) {
+            hints.push(clean.toLowerCase());
+        }
+    }
+    // Year patterns (4 digits)
+    const yearMatches = query.match(/\b(19|20)\d{2}\b/g);
+    if (yearMatches)
+        hints.push(...yearMatches);
+    return [...new Set(hints)];
+}
+/**
+ * Helper to create a flat column list with table context from a DataSchema.
+ */
+function flattenColumns(schema) {
+    const result = [];
+    for (const table of schema.tables) {
+        for (const col of table.columns) {
+            result.push({ ...col, table: table.name });
+        }
+    }
+    return result;
+}
+/**
+ * Find candidate columns from the schema that are relevant to the user's query.
+ *
+ * Scores columns by:
+ * - Direct column name match
+ * - Table name match
+ * - Sample value match (important for filtering)
+ * - Partial match
+ * - Filter hint matching (proper nouns, years)
+ * - Column type bonuses
+ *
+ * Also pulls in related columns from tables connected via foreign keys
+ * when filter values are found.
+ *
+ * Returns top candidates (up to ~25-30), ensuring a mix of categoricals and numerics.
+ */
+export function findCandidateColumns(query, schema) {
+    const allColumns = flattenColumns(schema);
+    const queryWords = query.toLowerCase().split(/\s+/);
+    const filterHints = extractFilterHints(query);
+    const scored = [];
+    // Track which tables have filter value matches
+    const filterMatchTables = new Set();
+    for (const col of allColumns) {
+        let score = 0;
+        const colLower = col.name.toLowerCase();
+        const tableLower = col.table.toLowerCase();
+        const sampleStr = col.sampleValues.join(' ').toLowerCase();
+        // Skip pure ID columns for category/value, but keep them for joins
+        const isIdCol = col.type === 'id' && col.uniqueCount > 100;
+        for (const word of queryWords) {
+            if (word.length < 3)
+                continue;
+            // Direct column name match
+            if (colLower.includes(word))
+                score += 10;
+            // Table name match
+            if (tableLower.includes(word))
+                score += 5;
+            // Sample value match (important for filtering!)
+            if (sampleStr.includes(word))
+                score += isIdCol ? 1 : 3;
+            // Partial match (e.g., "win" matches "wins")
+            if (colLower.includes(word.slice(0, -1)) && word.length > 3)
+                score += 4;
+        }
+        // Filter hint matching — high priority (proper nouns, years)
+        for (const hint of filterHints) {
+            if (sampleStr.includes(hint)) {
+                score += 15; // Strong signal — this column contains a value the user mentioned
+                filterMatchTables.add(col.table);
+            }
+            if (colLower.includes(hint))
+                score += 8;
+        }
+        // Bonus for interesting column types
+        if (!isIdCol && col.type === 'numeric')
+            score += 1;
+        if (!isIdCol && col.type === 'categorical' && col.uniqueCount > 2 && col.uniqueCount < 100)
+            score += 2;
+        if (col.type === 'date')
+            score += 1;
+        if (score > 0) {
+            scored.push({ col, score });
+        }
+    }
+    // Sort by score, take top 20
+    scored.sort((a, b) => b.score - a.score);
+    const candidates = scored.slice(0, 20).map(s => s.col);
+    const candidateKeys = new Set(candidates.map(c => `${c.table}.${c.name}`));
+    // Pull in related columns from tables that had filter matches (via foreign keys)
+    for (const table of filterMatchTables) {
+        for (const fk of schema.foreignKeys) {
+            let relatedTable = null;
+            if (fk.fromTable === table)
+                relatedTable = fk.toTable;
+            if (fk.toTable === table)
+                relatedTable = fk.fromTable;
+            if (relatedTable) {
+                // Add useful columns from the related table
+                const relatedCols = allColumns.filter(c => c.table === relatedTable &&
+                    !candidateKeys.has(`${c.table}.${c.name}`) &&
+                    (c.type === 'numeric' || c.type === 'categorical' || c.type === 'date'));
+                for (const rc of relatedCols.slice(0, 5)) {
+                    candidates.push(rc);
+                    candidateKeys.add(`${rc.table}.${rc.name}`);
+                }
+            }
+        }
+    }
+    // Ensure we have some categoricals and numerics
+    if (candidates.filter(c => c.type === 'categorical').length === 0) {
+        const goodCats = allColumns.filter(c => c.type === 'categorical' &&
+            c.uniqueCount > 2 &&
+            c.uniqueCount < 100 &&
+            !candidateKeys.has(`${c.table}.${c.name}`));
+        for (const gc of goodCats.slice(0, 3)) {
+            candidates.push(gc);
+        }
+    }
+    if (candidates.filter(c => c.type === 'numeric').length === 0) {
+        const goodNums = allColumns.filter(c => c.type === 'numeric' && !candidateKeys.has(`${c.table}.${c.name}`));
+        for (const gn of goodNums.slice(0, 3)) {
+            candidates.push(gn);
+        }
+    }
+    return candidates;
+}
+//# sourceMappingURL=candidate-matcher.js.map

package/dist/src/query-engine/candidate-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-matcher.js","sourceRoot":"","sources":["../../../src/query-engine/candidate-matcher.ts"],"names":[],"mappings":"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"}

package/dist/src/query-engine/chart-detector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Chart Detector — Determine chart type from result shape.
+ *
+ * Extracted from determineChartType() in the POC.
+ * Returns a string hint for the visualization layer.
+ */
+import type { LLMColumnSelection } from '../types.js';
+/**
+ * Determine the best chart type based on the query result data shape
+ * and the LLM selection metadata.
+ *
+ * Chart type hints returned:
+ * - 'scalar'                   — single value, no category
+ * - 'pie'                      — few categories (<=6), or percentage without series
+ * - 'bar'                      — moderate categories (<=25)
+ * - 'treemap'                  — many categories (>25)
+ * - 'line'                     — date/year-based categories over time
+ * - 'stacked-bar'              — two-dimensional, non-date categories
+ * - 'stacked-line'             — two-dimensional, date categories or top_n_per_group
+ * - 'stacked-bar-percentage'   — percentage with series column
+ * - 'grouped-bar'              — top_n_per_group, non-date
+ * - 'multi-line'               — multi-measure, date categories
+ * - 'grouped-bar-dual-axis'    — multi-measure, non-date categories
+ */
+export declare function determineChartType(data: Record<string, any>[], selection: LLMColumnSelection): string;
+//# sourceMappingURL=chart-detector.d.ts.map

package/dist/src/query-engine/chart-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-detector.d.ts","sourceRoot":"","sources":["../../../src/query-engine/chart-detector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAC3B,SAAS,EAAE,kBAAkB,GAC5B,MAAM,CAoCR"}

package/dist/src/query-engine/chart-detector.js

@@ -0,0 +1,61 @@
+/**
+ * Chart Detector — Determine chart type from result shape.
+ *
+ * Extracted from determineChartType() in the POC.
+ * Returns a string hint for the visualization layer.
+ */
+/**
+ * Determine the best chart type based on the query result data shape
+ * and the LLM selection metadata.
+ *
+ * Chart type hints returned:
+ * - 'scalar'                   — single value, no category
+ * - 'pie'                      — few categories (<=6), or percentage without series
+ * - 'bar'                      — moderate categories (<=25)
+ * - 'treemap'                  — many categories (>25)
+ * - 'line'                     — date/year-based categories over time
+ * - 'stacked-bar'              — two-dimensional, non-date categories
+ * - 'stacked-line'             — two-dimensional, date categories or top_n_per_group
+ * - 'stacked-bar-percentage'   — percentage with series column
+ * - 'grouped-bar'              — top_n_per_group, non-date
+ * - 'multi-line'               — multi-measure, date categories
+ * - 'grouped-bar-dual-axis'    — multi-measure, non-date categories
+ */
+export function determineChartType(data, selection) {
+    if (!selection.category_column)
+        return 'scalar';
+    if (data.length === 0)
+        return 'scalar';
+    if (data.length === 1 && !selection.series_column)
+        return 'scalar';
+    const categories = [...new Set(data.map(r => r.category))];
+    const looksLikeDate = categories.every((c) => /^\d{4}/.test(String(c)));
+    // Multi-measure (has value_2)
+    if (data.some(r => r.value_2 !== undefined)) {
+        return looksLikeDate ? 'multi-line' : 'grouped-bar-dual-axis';
+    }
+    // Percentage
+    if (selection.computed === 'percentage') {
+        return selection.series_column ? 'stacked-bar-percentage' : 'pie';
+    }
+    // Top N per group
+    if (selection.top_n_per_group) {
+        return looksLikeDate ? 'stacked-line' : 'grouped-bar';
+    }
+    // Two-dimensional data (has series column)
+    if (selection.series_column && data.some(r => r.series)) {
+        if (looksLikeDate)
+            return 'stacked-line';
+        return 'stacked-bar';
+    }
+    // Check if categories look like dates/years
+    if (looksLikeDate && data.length > 3)
+        return 'line';
+    // Few categories -> pie, many -> bar
+    if (data.length <= 6)
+        return 'pie';
+    if (data.length <= 25)
+        return 'bar';
+    return 'treemap';
+}
+//# sourceMappingURL=chart-detector.js.map

package/dist/src/query-engine/chart-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-detector.js","sourceRoot":"","sources":["../../../src/query-engine/chart-detector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAA2B,EAC3B,SAA6B;IAE7B,IAAI,CAAC,SAAS,CAAC,eAAe;QAAE,OAAO,QAAQ,CAAC;IAChD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa;QAAE,OAAO,QAAQ,CAAC;IAEnE,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E,8BAA8B;IAC9B,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,EAAE,CAAC;QAC5C,OAAO,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAChE,CAAC;IAED,aAAa;IACb,IAAI,SAAS,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QACxC,OAAO,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,KAAK,CAAC;IACpE,CAAC;IAED,kBAAkB;IAClB,IAAI,SAAS,CAAC,eAAe,EAAE,CAAC;QAC9B,OAAO,aAAa,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC;IACxD,CAAC;IAED,2CAA2C;IAC3C,IAAI,SAAS,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,IAAI,aAAa;YAAE,OAAO,cAAc,CAAC;QACzC,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,4CAA4C;IAC5C,IAAI,aAAa,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAEpD,qCAAqC;IACrC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,SAAS,CAAC;AACnB,CAAC"}