@zlens/notebook 0.0.0-stage → 0.1.0

package/dist/execute.js

@@ -0,0 +1,287 @@
+import { NodeKind, blockSemanticRuntimeBindings, parse, } from '@zlens/core';
+import { resolveSemanticRefs, hasSemanticRefs } from './semantic-refs.js';
+export function buildExecutionPlan(cell, options) {
+    if (cell.type === 'markdown' || cell.type === 'chart') {
+        return null;
+    }
+    if (cell.type === 'sql') {
+        // Resolve @metric(name) and @dim(name) references in SQL cells
+        let resolvedSql = cell.source;
+        if (options?.semanticLayer && hasSemanticRefs(cell.source)) {
+            const resolution = resolveSemanticRefs(cell.source, options.semanticLayer, {
+                tableMapping: options.tableMapping,
+            });
+            if (resolution.unresolvedRefs.length > 0) {
+                throw new Error(`Unresolved semantic references in SQL cell: ${resolution.unresolvedRefs.join(', ')}. ` +
+                    'Check that these metrics/dimensions exist in your semantic layer.');
+            }
+            resolvedSql = resolution.resolvedSql;
+        }
+        return {
+            title: cell.title || 'SQL cell',
+            sql: resolvedSql,
+            sqlParams: [],
+            variables: {},
+            chartConfig: cell.config,
+            tests: [],
+        };
+    }
+    const program = parse(cell.source);
+    const block = program.statements.find((statement) => statement.kind === NodeKind.BlockDecl);
+    if (!block) {
+        throw new Error('ZLens notebook cells must contain a block declaration.');
+    }
+    // Semantic blocks: compose SQL from the semantic layer
+    if (block.blockType === 'semantic') {
+        return buildSemanticPlan(block, options?.semanticLayer, options?.driver, options?.tableMapping, options?.parameters, options?.semanticSql);
+    }
+    if (block.blockType !== 'custom') {
+        throw new Error(`Unsupported block type "${block.blockType}". Only "custom" and "semantic" blocks can run in the notebook.`);
+    }
+    if (!block.query) {
+        throw new Error('ZLens notebook block is missing a query field.');
+    }
+    const processed = applyRLSDecorators(block.decorators, processSQL(block.query.rawSQL, block.query.interpolations));
+    const chartConfig = block.visualization ? lowerChartConfig(block.visualization.properties) : undefined;
+    const variables = Object.fromEntries((block.params?.params ?? [])
+        .filter((param) => param.initializer)
+        .map((param) => [param.name, evaluateExpression(param.initializer)]));
+    return {
+        title: block.name,
+        sql: processed.sql,
+        sqlParams: processed.params,
+        variables,
+        chartConfig,
+        tests: (block.tests ?? []).map((test) => ({
+            field: test.field,
+            operator: test.operator,
+            expected: evaluateExpression(test.expected),
+        })),
+    };
+}
+function lowerChartConfig(properties) {
+    const config = {};
+    for (const property of properties) {
+        const value = evaluateExpression(property.value);
+        switch (property.name) {
+            case 'chart':
+                config.chart = String(value);
+                break;
+            case 'x':
+                config.x = String(value);
+                break;
+            case 'y':
+                config.y = String(value);
+                break;
+            case 'y2':
+                config.y2 = String(value);
+                break;
+            case 'color':
+                config.color = String(value);
+                break;
+        }
+    }
+    return config;
+}
+function processSQL(rawSQL, interpolations) {
+    if (interpolations.length === 0) {
+        return { sql: rawSQL, params: [] };
+    }
+    let sql = rawSQL;
+    const params = [];
+    const sorted = [...interpolations].sort((a, b) => b.offsetInSQL - a.offsetInSQL);
+    let position = interpolations.length;
+    for (const interpolation of sorted) {
+        const placeholder = `$${position}`;
+        const from = interpolation.offsetInSQL;
+        const rest = sql.slice(from);
+        const pattern = new RegExp(`^\\$\\{${interpolation.variableName}\\}|^\\{${interpolation.variableName}\\}`);
+        const match = rest.match(pattern);
+        if (!match) {
+            position -= 1;
+            continue;
+        }
+        sql = sql.slice(0, from) + placeholder + sql.slice(from + match[0].length);
+        params.unshift({ name: interpolation.variableName, position });
+        position -= 1;
+    }
+    return { sql, params };
+}
+function buildSemanticPlan(block, semanticLayer, driver, tableMapping, parameters, semanticSql) {
+    if (!semanticLayer) {
+        throw new Error('Semantic block requires a semantic-layer/ configuration. ' +
+            'Add metric and dimension YAML files to your project\'s semantic-layer/ directory.');
+    }
+    // Extract metric references: metricsRef (array) takes precedence over metricRef (single)
+    const metrics = [];
+    const dimensions = [];
+    if (block.metricsRef && block.metricsRef.length > 0) {
+        metrics.push(...block.metricsRef);
+    }
+    else if (block.metricRef) {
+        metrics.push(block.metricRef);
+    }
+    if (block.dimensionsRef && block.dimensionsRef.length > 0) {
+        dimensions.push(...block.dimensionsRef);
+    }
+    // Also extract dimensions/metrics from block params if they reference names
+    for (const param of block.params?.params ?? []) {
+        if (!param.initializer)
+            continue;
+        const val = evaluateExpression(param.initializer);
+        if (param.name === 'dimensions' && Array.isArray(val)) {
+            dimensions.push(...val.map(String));
+        }
+        else if (param.name === 'metrics' && Array.isArray(val)) {
+            metrics.push(...val.map(String));
+        }
+    }
+    if (metrics.length === 0) {
+        throw new Error(`Semantic block "${block.name}" has no metric references. ` +
+            'Add metrics = ["metric1", "metric2"] to your block declaration.');
+    }
+    const runtimeBindings = blockSemanticRuntimeBindings(block, parameters);
+    const composed = semanticSql
+        ? { sql: semanticSql }
+        : semanticLayer.composeQuery({
+            metrics,
+            dimensions,
+            ...(block.timeDimension && block.granularity
+                ? { timeDimension: { name: block.timeDimension, granularity: block.granularity } }
+                : {}),
+            ...(runtimeBindings.filters.length > 0 ? { filters: runtimeBindings.filters } : {}),
+            ...((runtimeBindings.limit ?? block.limit) !== undefined
+                ? { limit: runtimeBindings.limit ?? block.limit }
+                : {}),
+            driver,
+            tableMapping,
+        });
+    if (!composed) {
+        // Distinguish the three real causes instead of sending users to check
+        // definitions that are usually fine: (a) the metric genuinely is not
+        // defined, (b) it exists but is a derived/ratio/cumulative metric DQL
+        // cannot compose natively (needs dbt Cloud Semantic Layer or local
+        // MetricFlow), (c) everything resolves but the dimension set is unjoinable.
+        const reasons = metrics.map((name) => {
+            if (semanticLayer.canComposeMetric(name))
+                return null;
+            const metric = semanticLayer.getMetric(name);
+            if (!metric)
+                return `metric "${name}" is not defined in the semantic layer`;
+            const kind = metric.metricType || metric.type || 'metric';
+            return `metric "${name}" exists but is a ${kind} metric ZLens cannot compose natively — run it through a full semantic runtime (dbt Cloud Semantic Layer or local MetricFlow)`;
+        }).filter((reason) => Boolean(reason));
+        throw new Error(reasons.length > 0
+            ? `Could not compose SQL for semantic block "${block.name}": ${reasons.join('; ')}.`
+            : `Could not compose SQL for semantic block "${block.name}". The metrics resolved, but the selected dimensions do not share a governed join path with them — remove or replace the unjoinable dimension.`);
+    }
+    const chartConfig = block.visualization ? lowerChartConfig(block.visualization.properties) : undefined;
+    const variables = Object.fromEntries((block.params?.params ?? [])
+        .filter((param) => param.initializer)
+        .map((param) => [param.name, evaluateExpression(param.initializer)]));
+    const processed = applyRLSDecorators(block.decorators, { sql: composed.sql, params: [] });
+    return {
+        title: block.name,
+        sql: processed.sql,
+        sqlParams: processed.params,
+        variables,
+        chartConfig,
+        tests: (block.tests ?? []).map((test) => ({
+            field: test.field,
+            operator: test.operator,
+            expected: evaluateExpression(test.expected),
+        })),
+    };
+}
+const SAFE_RLS_COLUMN = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const RLS_TEMPLATE_VARIABLE = /^\{([A-Za-z_][A-Za-z0-9_.]*)\}$/;
+function applyRLSDecorators(decorators, processed) {
+    const rlsDecorators = decorators.filter((d) => d.name === 'rls');
+    if (rlsDecorators.length === 0)
+        return processed;
+    const clauses = [];
+    const params = [...processed.params];
+    let nextPosition = params.reduce((max, p) => Math.max(max, p.position), 0);
+    let literalCounter = 0;
+    for (const rls of rlsDecorators) {
+        if (rls.arguments.length < 2)
+            continue;
+        const column = normalizeRLSColumn(rls.arguments[0]);
+        if (!column)
+            continue;
+        const binding = resolveRLSValueBinding(rls.arguments[1]);
+        if (!binding)
+            continue;
+        nextPosition += 1;
+        if (binding.type === 'variable') {
+            params.push({ name: binding.variableName, position: nextPosition });
+        }
+        else {
+            literalCounter += 1;
+            params.push({
+                name: `__rls_literal_${literalCounter}`,
+                position: nextPosition,
+                literalValue: binding.literalValue,
+            });
+        }
+        clauses.push(`${column} = COALESCE($${nextPosition}, ${column})`);
+    }
+    if (clauses.length === 0)
+        return { sql: processed.sql, params };
+    return {
+        sql: `SELECT * FROM (${processed.sql}) _dql_rls WHERE ${clauses.join(' AND ')}`,
+        params,
+    };
+}
+function normalizeRLSColumn(arg) {
+    const raw = arg.kind === NodeKind.StringLiteral
+        ? arg.value
+        : arg.kind === NodeKind.Identifier
+            ? arg.name
+            : evaluateExpression(arg);
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    return SAFE_RLS_COLUMN.test(trimmed) ? trimmed : null;
+}
+function resolveRLSValueBinding(arg) {
+    if (arg.kind === NodeKind.StringLiteral) {
+        const raw = String(arg.value ?? '');
+        const match = raw.trim().match(RLS_TEMPLATE_VARIABLE);
+        if (match)
+            return { type: 'variable', variableName: match[1] };
+        return { type: 'literal', literalValue: raw };
+    }
+    if (arg.kind === NodeKind.Identifier)
+        return { type: 'variable', variableName: arg.name };
+    if (arg.kind === NodeKind.NumberLiteral || arg.kind === NodeKind.BooleanLiteral) {
+        return { type: 'literal', literalValue: arg.value };
+    }
+    const value = evaluateExpression(arg);
+    if (value !== undefined)
+        return { type: 'literal', literalValue: value };
+    return null;
+}
+function evaluateExpression(node) {
+    switch (node.kind) {
+        case NodeKind.StringLiteral:
+            return node.value;
+        case NodeKind.NumberLiteral:
+            return node.value;
+        case NodeKind.BooleanLiteral:
+            return node.value;
+        case NodeKind.Identifier:
+            return node.name;
+        case NodeKind.ArrayLiteral:
+            return node.elements.map((element) => evaluateExpression(element));
+        case NodeKind.IntervalExpr:
+            return node.value;
+        case NodeKind.BinaryExpr:
+            return `${evaluateExpression(node.left)} ${node.operator} ${evaluateExpression(node.right)}`;
+        case NodeKind.FunctionCall:
+            return node.callee;
+        case NodeKind.TemplateString:
+            return node.parts.map((part) => (typeof part === 'string' ? part : String(evaluateExpression(part)))).join('');
+    }
+}
+//# sourceMappingURL=execute.js.map

package/dist/execute.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './document.js';
+export * from './execute.js';
+export * from './connector-forms.js';
+export * from './semantic-refs.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './document.js';
+export * from './execute.js';
+export * from './connector-forms.js';
+export * from './semantic-refs.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/semantic-refs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Semantic reference resolver for SQL cells.
+ *
+ * Resolves `@metric(name)` and `@dim(name)` references in plain SQL strings
+ * by looking up the metric/dimension definition in the SemanticLayer and
+ * inlining the SQL expression.
+ *
+ * Example:
+ *   Input:  SELECT @dim(segment), @metric(total_revenue) FROM fct_revenue GROUP BY @dim(segment)
+ *   Output: SELECT segment_tier AS segment, SUM(amount) AS total_revenue FROM fct_revenue GROUP BY segment_tier
+ */
+import type { SemanticLayer } from '@zlens/core';
+export interface SemanticRefResolutionOptions {
+    /** Maps semantic model names to live, schema-qualified database relations. */
+    tableMapping?: Record<string, string>;
+    /** Maximum rows returned when a standalone dimension is explored. */
+    standaloneDimensionLimit?: number;
+}
+export interface SemanticRefResolution {
+    /** The resolved SQL with all semantic references expanded. */
+    resolvedSql: string;
+    /** Names of metrics that were resolved. */
+    resolvedMetrics: string[];
+    /** Names of dimensions that were resolved. */
+    resolvedDimensions: string[];
+    /** Any references that could not be resolved. */
+    unresolvedRefs: string[];
+}
+/**
+ * Check if a SQL string contains any semantic references.
+ */
+export declare function hasSemanticRefs(sql: string): boolean;
+/** Check whether the entire SQL cell is one semantic reference. */
+export declare function hasStandaloneSemanticRef(sql: string): boolean;
+/**
+ * Resolve all `@metric(name)` and `@dim(name)` references in a SQL string.
+ *
+ * - `@metric(total_revenue)` → expands to the metric's SQL expression with an alias
+ * - `@dim(segment)` or `@dimension(segment)` → expands to the dimension's SQL expression with an alias
+ *
+ * If a reference can't be found in the semantic layer, it is left as-is and
+ * added to `unresolvedRefs` so the caller can report a helpful error.
+ */
+export declare function resolveSemanticRefs(sql: string, semanticLayer: SemanticLayer | undefined, options?: SemanticRefResolutionOptions): SemanticRefResolution;
+/**
+ * Get a list of available semantic references for autocomplete.
+ */
+export declare function getSemanticRefCompletions(semanticLayer: SemanticLayer | undefined): Array<{
+    type: 'metric' | 'dimension';
+    name: string;
+    label: string;
+    description: string;
+}>;
+//# sourceMappingURL=semantic-refs.d.ts.map

package/dist/semantic-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-refs.d.ts","sourceRoot":"","sources":["../src/semantic-refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAyC,aAAa,EAAE,MAAM,aAAa,CAAC;AAMxF,MAAM,WAAW,4BAA4B;IAC3C,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qEAAqE;IACrE,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iDAAiD;IACjD,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAIpD;AAED,mEAAmE;AACnE,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,aAAa,GAAG,SAAS,EACxC,OAAO,CAAC,EAAE,4BAA4B,GACrC,qBAAqB,CA2EvB;AAgHD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,aAAa,GAAG,SAAS,GACvC,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB3F"}

package/dist/semantic-refs.js

@@ -0,0 +1,216 @@
+/**
+ * Semantic reference resolver for SQL cells.
+ *
+ * Resolves `@metric(name)` and `@dim(name)` references in plain SQL strings
+ * by looking up the metric/dimension definition in the SemanticLayer and
+ * inlining the SQL expression.
+ *
+ * Example:
+ *   Input:  SELECT @dim(segment), @metric(total_revenue) FROM fct_revenue GROUP BY @dim(segment)
+ *   Output: SELECT segment_tier AS segment, SUM(amount) AS total_revenue FROM fct_revenue GROUP BY segment_tier
+ */
+/** Pattern to match @metric(name) or @dim(name) references. */
+const SEMANTIC_REF_PATTERN = /@(metric|dim|dimension)\(\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\)/g;
+const STANDALONE_SEMANTIC_REF_PATTERN = /^\s*@(metric|dim|dimension)\(\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\)\s*;?\s*$/;
+/**
+ * Check if a SQL string contains any semantic references.
+ */
+export function hasSemanticRefs(sql) {
+    // New regex each call — the module-level /g pattern carries lastIndex state
+    // across calls and would return false on every second call for the same SQL.
+    return /@(metric|dim|dimension)\(\s*[a-zA-Z_][a-zA-Z0-9_.]*\s*\)/.test(sql);
+}
+/** Check whether the entire SQL cell is one semantic reference. */
+export function hasStandaloneSemanticRef(sql) {
+    return STANDALONE_SEMANTIC_REF_PATTERN.test(sql);
+}
+/**
+ * Resolve all `@metric(name)` and `@dim(name)` references in a SQL string.
+ *
+ * - `@metric(total_revenue)` → expands to the metric's SQL expression with an alias
+ * - `@dim(segment)` or `@dimension(segment)` → expands to the dimension's SQL expression with an alias
+ *
+ * If a reference can't be found in the semantic layer, it is left as-is and
+ * added to `unresolvedRefs` so the caller can report a helpful error.
+ */
+export function resolveSemanticRefs(sql, semanticLayer, options) {
+    const resolvedMetrics = [];
+    const resolvedDimensions = [];
+    const unresolvedRefs = [];
+    if (!semanticLayer) {
+        // No semantic layer — check if there are refs that need resolving
+        const refs = [];
+        sql.replace(SEMANTIC_REF_PATTERN, (_match, _type, name) => {
+            refs.push(name);
+            return _match;
+        });
+        if (refs.length > 0) {
+            return {
+                resolvedSql: sql,
+                resolvedMetrics: [],
+                resolvedDimensions: [],
+                unresolvedRefs: refs,
+            };
+        }
+        return { resolvedSql: sql, resolvedMetrics: [], resolvedDimensions: [], unresolvedRefs: [] };
+    }
+    // The notebook library lets users drag a semantic item into the canvas to
+    // create a cell whose complete source is `@dim(...)` or `@metric(...)`.
+    // Those references are expressions inside normal SQL, but a standalone cell
+    // needs a complete query. Compile it from semantic ownership plus the live
+    // table mapping so this works for any project/schema, not a fixture-specific
+    // relation name.
+    const standalone = sql.match(STANDALONE_SEMANTIC_REF_PATTERN);
+    if (standalone) {
+        return resolveStandaloneSemanticRef(standalone[1], standalone[2], semanticLayer, options);
+    }
+    // Track which position in the SQL each ref appears to handle GROUP BY correctly
+    // (in GROUP BY, we should NOT include the alias or aggregation wrapper)
+    const resolvedSql = sql.replace(SEMANTIC_REF_PATTERN, (match, refType, name) => {
+        if (refType === 'metric') {
+            const metric = semanticLayer.getMetric(name);
+            if (!metric) {
+                unresolvedRefs.push(`metric:${name}`);
+                return match;
+            }
+            resolvedMetrics.push(name);
+            // In SELECT context: wrap with aggregation and alias
+            // In GROUP BY / WHERE context: just the raw expression
+            // We use a heuristic: check if this ref appears after GROUP BY, ORDER BY, WHERE, HAVING
+            return `${metric.sql} AS ${sanitizeAlias(name)}`;
+        }
+        // dim or dimension
+        const dim = semanticLayer.getDimension(name);
+        if (!dim) {
+            unresolvedRefs.push(`dimension:${name}`);
+            return match;
+        }
+        resolvedDimensions.push(name);
+        return `${dim.sql} AS ${sanitizeAlias(name)}`;
+    });
+    // Second pass: fix GROUP BY / ORDER BY / WHERE / HAVING clauses
+    // In these clauses, we should use just the raw SQL without alias
+    const fixedSql = fixClauseRefs(resolvedSql, semanticLayer);
+    return {
+        resolvedSql: fixedSql,
+        resolvedMetrics,
+        resolvedDimensions,
+        unresolvedRefs,
+    };
+}
+function resolveStandaloneSemanticRef(refType, name, semanticLayer, options) {
+    if (refType === 'metric') {
+        const metric = semanticLayer.getMetric(name);
+        if (!metric)
+            return unresolvedStandalone(`metric:${name}`, `@metric(${name})`);
+        const composed = composeStandaloneMetric(metric, semanticLayer, options?.tableMapping);
+        if (!composed) {
+            return unresolvedStandalone(`metric:${name} (requires a full semantic query or MetricFlow)`, `@metric(${name})`);
+        }
+        return {
+            resolvedSql: composed,
+            resolvedMetrics: [name],
+            resolvedDimensions: [],
+            unresolvedRefs: [],
+        };
+    }
+    const dimension = semanticLayer.getDimension(name);
+    if (!dimension?.table || !dimension.sql.trim()) {
+        return unresolvedStandalone(`dimension:${name}`, `@dim(${name})`);
+    }
+    const limit = clampStandaloneDimensionLimit(options?.standaloneDimensionLimit);
+    const table = options?.tableMapping?.[dimension.table] ?? dimension.table;
+    const alias = sanitizeAlias(name);
+    const tableAlias = sanitizeAlias(dimension.table.split('.').pop() ?? dimension.table);
+    const expression = qualifyDimensionExpression(dimension, tableAlias);
+    return {
+        resolvedSql: [
+            `SELECT DISTINCT ${expression} AS ${alias}`,
+            `FROM ${table} AS ${tableAlias}`,
+            `ORDER BY ${alias}`,
+            `LIMIT ${limit}`,
+        ].join('\n'),
+        resolvedMetrics: [],
+        resolvedDimensions: [name],
+        unresolvedRefs: [],
+    };
+}
+function composeStandaloneMetric(metric, semanticLayer, tableMapping) {
+    return semanticLayer.composeQuery({
+        metrics: [metric.name],
+        dimensions: [],
+        tableMapping,
+    })?.sql ?? null;
+}
+function qualifyDimensionExpression(dimension, tableAlias) {
+    if (!tableAlias)
+        return dimension.sql;
+    const prefix = `${dimension.table}.`;
+    return dimension.sql.startsWith(prefix)
+        ? `${tableAlias}.${dimension.sql.slice(prefix.length)}`
+        : dimension.sql;
+}
+function clampStandaloneDimensionLimit(value) {
+    if (!Number.isFinite(value))
+        return 200;
+    return Math.max(1, Math.min(1000, Math.trunc(value)));
+}
+function unresolvedStandalone(ref, sql) {
+    return {
+        resolvedSql: sql,
+        resolvedMetrics: [],
+        resolvedDimensions: [],
+        unresolvedRefs: [ref],
+    };
+}
+/**
+ * In GROUP BY, ORDER BY, WHERE, HAVING clauses, replace "expr AS alias" with just "expr".
+ * This is needed because SQL doesn't allow aliases in GROUP BY for most databases.
+ */
+function fixClauseRefs(sql, semanticLayer) {
+    // Find all "expression AS alias" patterns that appear after GROUP BY, ORDER BY, WHERE, HAVING
+    const clausePattern = /\b(GROUP\s+BY|ORDER\s+BY|WHERE|HAVING)\b/gi;
+    const match = clausePattern.exec(sql);
+    if (!match)
+        return sql;
+    const clauseStart = match.index;
+    const beforeClause = sql.substring(0, clauseStart);
+    const clauseAndAfter = sql.substring(clauseStart);
+    // In the clause portion, strip " AS alias" from resolved refs
+    const fixed = clauseAndAfter.replace(/(\S+)\s+AS\s+([a-zA-Z_][a-zA-Z0-9_]*)/g, (_m, expr, _alias) => {
+        return expr;
+    });
+    return beforeClause + fixed;
+}
+/**
+ * Sanitize a name to be a valid SQL alias.
+ */
+function sanitizeAlias(name) {
+    return name.replace(/\./g, '_').replace(/[^a-zA-Z0-9_]/g, '');
+}
+/**
+ * Get a list of available semantic references for autocomplete.
+ */
+export function getSemanticRefCompletions(semanticLayer) {
+    if (!semanticLayer)
+        return [];
+    const completions = [];
+    for (const metric of semanticLayer.listMetrics()) {
+        completions.push({
+            type: 'metric',
+            name: metric.name,
+            label: metric.label,
+            description: metric.description ?? '',
+        });
+    }
+    for (const dim of semanticLayer.listDimensions()) {
+        completions.push({
+            type: 'dimension',
+            name: dim.name,
+            label: dim.label,
+            description: dim.description ?? '',
+        });
+    }
+    return completions;
+}
+//# sourceMappingURL=semantic-refs.js.map

package/dist/semantic-refs.js.map

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