diff --git a/src/analytics/contract/compile-clickhouse.ts b/src/analytics/contract/compile-clickhouse.ts new file mode 100644 index 0000000..5ff7071 --- /dev/null +++ b/src/analytics/contract/compile-clickhouse.ts @@ -0,0 +1,252 @@ +/** + * src/analytics/contract/compile-clickhouse.ts + * ============================================= + * BI-P016, compile target 1 of 2: the canonical `AnalyticsQueryRequest` + * becomes tenant-forced ClickHouse SQL. + * + * The BI-P011 guarantee is repeated here VERBATIM and by construction: + * + * * `FORCED_TENANT_PREDICATE` is condition[0] with no branch that can skip + * it, and the tenant value comes from the verified identity handed in by + * the engine — this function has no way to read one from a request, + * because `AnalyticsQueryRequest` has no tenant field. + * * every caller VALUE is a `param_*` binding; `sql` never contains one. + * * every caller NAME has already been resolved through the catalog + * (`resolveAnalyticsQuery`), and the resolved physical name is validated + * as an identifier a second time before it reaches the string. + * + * tests/analytics/query-request-tenant-forcing.test.ts asserts the predicate + * survives every request shape this compiler accepts, by ENUMERATING the + * shapes rather than spot-checking two of them. + */ +import { SiaxError } from '../../platform/errors'; +import { assertSafeIdentifier, FORCED_TENANT_PREDICATE, type CompiledQuery } from '../engine/query-compiler'; +import type { AnalyticsTable } from '../engine/schema'; +import type { ResolvedQuery, TimeGrain } from './query-request'; +import type { FilterOperator } from './query-request'; + +/** Grain -> ClickHouse truncation function. A closed map, never caller text. */ +const GRAIN_FN: Record = { + hour: 'toStartOfHour', + day: 'toStartOfDay', + week: 'toStartOfWeek', + month: 'toStartOfMonth', + quarter: 'toStartOfQuarter', + year: 'toStartOfYear', +}; + +/** + * Aggregation -> conditional-aggregate template. `count_distinct` uses + * `uniqExactIf` so a multi-metric request stays one scan instead of N. + */ +const AGG_IF: Record string> = { + sum: (p) => `sumIf(value, metric = {${p}:String})`, + avg: (p) => `avgIf(value, metric = {${p}:String})`, + min: (p) => `minIf(value, metric = {${p}:String})`, + max: (p) => `maxIf(value, metric = {${p}:String})`, + count: (p) => `countIf(metric = {${p}:String})`, + count_distinct: (p) => `uniqExactIf(event_id, metric = {${p}:String})`, +}; + +export interface ClickHouseCompileOptions { + /** From the VERIFIED CL0UD identity. Never from a request body. */ + tenant_id: string; + project_id?: string; + database: string; + table?: AnalyticsTable; + /** BI-P012 ceiling; `limit` is clamped to it, never raised by it. */ + maxResultRows: number; +} + +export interface CompiledAnalyticsQuery extends CompiledQuery { + /** Column alias -> caller-facing metric name, so the caller never sees `m0`. */ + metricAliases: Record; + /** Column alias -> caller-facing dimension name. */ + dimensionAliases: Record; + effectiveLimit: number; +} + +export function compileRequestToClickHouse( + resolved: ResolvedQuery, + opts: ClickHouseCompileOptions, +): CompiledAnalyticsQuery { + if (!opts.tenant_id || !opts.tenant_id.trim()) { + // Fail closed. A blank tenant must never compile to "no predicate". + throw new SiaxError('INVALID_REQUEST', '0pt.analytics', 'tenant_id is required on every analytics query'); + } + assertSafeIdentifier(opts.database, 'database'); + const table: AnalyticsTable = opts.table ?? 'opt_analytics_event'; + assertSafeIdentifier(table, 'table'); + + const params: Record = { param_tenant: opts.tenant_id }; + // ── the forced predicate. First condition, always, no branch. ───────── + const conditions: string[] = [FORCED_TENANT_PREDICATE]; + + if (opts.project_id) { + conditions.push('project_id = {project:String}'); + params.param_project = opts.project_id; + } + conditions.push('dataset_id = {dataset:String}'); + params.param_dataset = resolved.dataset_id; + + // ── metrics: bound keys, compiler-generated aliases ─────────────────── + const selectParts: string[] = []; + const groupParts: string[] = []; + const dimensionAliases: Record = {}; + const metricAliases: Record = {}; + const metricKeyParams: string[] = []; + + resolved.dimensions.forEach((d, i) => { + assertSafeIdentifier(d.field_name, 'dimension'); + const key = `d${i}`; + const alias = `dim_${i}`; + selectParts.push(`dim_values[indexOf(dim_names, {${key}:String})] AS ${alias}`); + groupParts.push(alias); + params[`param_${key}`] = d.field_name; + dimensionAliases[alias] = d.name; + }); + + // ── time grain: a GROUP BY bucket, from the closed GRAIN_FN map ─────── + const grain = resolved.request.timeRange?.grain; + if (grain) { + const timeCol = resolved.timeDimension ?? 'event_time'; + assertSafeIdentifier(timeCol, 'time dimension'); + const alias = 'time_bucket'; + selectParts.push(`${GRAIN_FN[grain]}(${timeCol}) AS ${alias}`); + groupParts.push(alias); + dimensionAliases[alias] = resolved.request.timeRange?.dimension ?? '__time'; + } + + resolved.metrics.forEach((m, i) => { + const key = `m${i}`; + const alias = `metric_${i}`; + const template = AGG_IF[m.aggregation]; + if (!template) { + throw new SiaxError('INVALID_REQUEST', '0pt.analytics', `unsupported aggregation "${m.aggregation}"`); + } + selectParts.push(`${template(key)} AS ${alias}`); + params[`param_${key}`] = m.event_metric_key; + metricKeyParams.push(`{${key}:String}`); + metricAliases[alias] = m.name; + }); + + // Restrict the SCAN to the requested metric keys — a correctness AND a cost + // measure: without it every metric row in the dataset is read to be thrown + // away by the `If` conditions. + conditions.push(`metric IN (${metricKeyParams.join(', ')})`); + + // ── time range: bound instants, half-open ───────────────────────────── + const tr = resolved.request.timeRange; + if (tr?.from || tr?.to) { + const timeCol = resolved.timeDimension ?? 'event_time'; + assertSafeIdentifier(timeCol, 'time dimension'); + if (tr.from) { + conditions.push(`${timeCol} >= parseDateTime64BestEffort({fromTime:String})`); + params.param_fromTime = tr.from; + } + if (tr.to) { + conditions.push(`${timeCol} < parseDateTime64BestEffort({toTime:String})`); + params.param_toTime = tr.to; + } + } + + // ── filters: closed operator set, values always bound ───────────────── + resolved.filters.forEach((entry, i) => { + assertSafeIdentifier(entry.dimension.field_name, 'dimension'); + const nameKey = `fn${i}`; + params[`param_${nameKey}`] = entry.dimension.field_name; + const lhs = `dim_values[indexOf(dim_names, {${nameKey}:String})]`; + conditions.push(renderFilter(lhs, nameKey, entry.filter.operator, entry.filter.values ?? [], i, params)); + }); + + // ── order by: resolved back onto compiler-generated aliases only ────── + const aliasForName = new Map(); + for (const [alias, name] of Object.entries(dimensionAliases)) aliasForName.set(name, alias); + for (const [alias, name] of Object.entries(metricAliases)) aliasForName.set(name, alias); + const orderParts: string[] = []; + for (const o of resolved.request.orderBy ?? []) { + const alias = aliasForName.get(o.ref); + if (!alias) { + // Cannot happen after parseAnalyticsQueryRequest, which already refuses + // an orderBy that is not selected. Kept as a hard stop rather than a + // silent skip: a guard that quietly does nothing is how a bypass hides. + throw new SiaxError('INVALID_REQUEST', '0pt.analytics', `orderBy "${o.ref}" is not selected`); + } + orderParts.push(`${alias} ${o.direction === 'asc' ? 'ASC' : 'DESC'}`); + } + + const requested = resolved.request.limit ?? 1000; + const effectiveLimit = Math.max(1, Math.min(Math.floor(requested), opts.maxResultRows)); + + const sql = + `SELECT ${selectParts.join(', ')} ` + + `FROM ${opts.database}.${table} ` + + `WHERE ${conditions.join(' AND ')}` + + (groupParts.length ? ` GROUP BY ${groupParts.join(', ')}` : '') + + (orderParts.length ? ` ORDER BY ${orderParts.join(', ')}` : '') + + ` LIMIT ${effectiveLimit} FORMAT JSON`; + + return { + sql, + params, + forcedTenantPredicate: FORCED_TENANT_PREDICATE, + table, + metricAliases, + dimensionAliases, + effectiveLimit, + }; +} + +function renderFilter( + lhs: string, + nameKey: string, + operator: FilterOperator, + values: string[], + index: number, + params: Record, +): string { + const bind = (v: string, suffix: string): string => { + const key = `fv${index}${suffix}`; + params[`param_${key}`] = v; + return `{${key}:String}`; + }; + switch (operator) { + case 'eq': + return `${lhs} = ${bind(values[0], '')}`; + case 'ne': + return `${lhs} != ${bind(values[0], '')}`; + case 'lt': + return `${lhs} < ${bind(values[0], '')}`; + case 'lte': + return `${lhs} <= ${bind(values[0], '')}`; + case 'gt': + return `${lhs} > ${bind(values[0], '')}`; + case 'gte': + return `${lhs} >= ${bind(values[0], '')}`; + case 'contains': + // `position(haystack, needle) > 0` keeps the needle a BOUND VALUE. + // A LIKE with a concatenated pattern would make it SQL text. + return `position(${lhs}, ${bind(values[0], '')}) > 0`; + case 'in': + case 'not_in': { + const bound = values.map((v, i) => bind(v, `_${i}`)); + return `${lhs} ${operator === 'in' ? 'IN' : 'NOT IN'} (${bound.join(', ')})`; + } + case 'is_null': + // Dimension values live in a paired-array map; an absent key yields '' + // rather than NULL, so "is null" means "the key is not present". The + // key itself is the already-bound `param_fn` — no new binding, and + // certainly no spliced identifier. + return `NOT has(dim_names, {${nameKey}:String})`; + case 'is_not_null': + return `has(dim_names, {${nameKey}:String})`; + default: { + const _never: never = operator; + throw new SiaxError( + 'INVALID_REQUEST', + '0pt.analytics', + `unsupported filter operator ${String(_never)}`, + ); + } + } +} diff --git a/src/analytics/contract/compile-semantic.ts b/src/analytics/contract/compile-semantic.ts new file mode 100644 index 0000000..8cb1ac8 --- /dev/null +++ b/src/analytics/contract/compile-semantic.ts @@ -0,0 +1,145 @@ +/** + * src/analytics/contract/compile-semantic.ts + * =========================================== + * BI-P016, compile target 2 of 2 — and the thing that makes BI-P016's DoD + * ("same request can compile to ClickHouse/semantic engine without consumer + * rewrite") a testable claim rather than a design intention. + * + * A `SemanticQuerySpec` is the engine-neutral form a semantic layer consumes. + * It is deliberately shaped like MetricFlow's query interface (metrics / + * group-by / where / order / limit / time-constraint) so BI-P029's + * `MetricFlowProvider` can execute it without an adapter, but it names + * nothing MetricFlow-specific: swapping MetricFlow for Cube or a hand-rolled + * compiler changes this file's CONSUMER, not this file, and never the + * product API. + * + * The `where` clauses here are STRUCTURED, not SQL strings. A semantic layer + * that accepts SQL predicate text (MetricFlow's `--where` does) would put a + * raw-SQL hole behind the closed DSL — so the spec carries operator+values + * and the provider renders them itself under its own escaping rules. + */ +import type { FilterOperator, ResolvedQuery, TimeGrain } from './query-request'; + +export interface SemanticMetricRef { + /** Canonical SIAX metric id — stable across semantic-engine replacement. */ + metric_id: string; + name: string; +} + +export interface SemanticGroupBy { + dimension_id: string; + name: string; + /** Set when this group-by is a time bucket rather than a categorical one. */ + grain?: TimeGrain; +} + +export interface SemanticWhere { + dimension_id: string; + name: string; + operator: FilterOperator; + values: string[]; +} + +export interface SemanticOrderBy { + ref: string; + direction: 'asc' | 'desc'; +} + +export interface SemanticTimeConstraint { + /** Inclusive lower bound. */ + start?: string; + /** EXCLUSIVE upper bound — matched to the ClickHouse target exactly. */ + end?: string; + dimension?: string; +} + +export interface SemanticQuerySpec { + dataset_id: string; + semantic_model_version?: number; + metrics: SemanticMetricRef[]; + groupBy: SemanticGroupBy[]; + where: SemanticWhere[]; + orderBy: SemanticOrderBy[]; + limit: number; + timeConstraint?: SemanticTimeConstraint; + format: 'json' | 'arrow_ipc'; +} + +export function compileRequestToSemantic(resolved: ResolvedQuery): SemanticQuerySpec { + const groupBy: SemanticGroupBy[] = resolved.dimensions.map((d) => ({ + dimension_id: d.dimension_id, + name: d.name, + })); + const grain = resolved.request.timeRange?.grain; + if (grain) { + groupBy.push({ + dimension_id: resolved.request.timeRange?.dimension ?? '__time', + name: resolved.request.timeRange?.dimension ?? '__time', + grain, + }); + } + return { + dataset_id: resolved.dataset_id, + semantic_model_version: resolved.semantic_model_version, + metrics: resolved.metrics.map((m) => ({ metric_id: m.metric_id, name: m.name })), + groupBy, + where: resolved.filters.map((f) => ({ + dimension_id: f.dimension.dimension_id, + name: f.dimension.name, + operator: f.filter.operator, + values: f.filter.values ?? [], + })), + orderBy: (resolved.request.orderBy ?? []).map((o) => ({ ref: o.ref, direction: o.direction })), + limit: resolved.request.limit ?? 1000, + timeConstraint: + resolved.request.timeRange && (resolved.request.timeRange.from || resolved.request.timeRange.to) + ? { + start: resolved.request.timeRange.from, + end: resolved.request.timeRange.to, + dimension: resolved.request.timeRange.dimension, + } + : undefined, + format: resolved.request.format ?? 'json', + }; +} + +/** + * The comparable SHAPE of a compiled query, target-independent. + * + * BI-P016's DoD is about semantic equivalence, and the honest way to test + * that is to project both targets onto the same tuple and demand equality — + * not to eyeball two strings. `tests/analytics/query-request-contract.test.ts` + * builds this from the ClickHouse SQL by PARSING the compiled artefact, so a + * compiler that quietly drops a filter fails the comparison. + */ +export interface QueryShape { + dataset_id: string; + metrics: string[]; + dimensions: string[]; + filters: Array<{ dimension: string; operator: FilterOperator; values: string[] }>; + order: string[]; + limit: number; + timeFrom?: string; + timeTo?: string; + grain?: TimeGrain; +} + +export function shapeOfSemanticSpec(spec: SemanticQuerySpec): QueryShape { + const timeBucket = spec.groupBy.find((g) => g.grain); + return { + dataset_id: spec.dataset_id, + metrics: spec.metrics.map((m) => m.name).sort(), + dimensions: spec.groupBy + .filter((g) => !g.grain) + .map((g) => g.name) + .sort(), + filters: spec.where + .map((w) => ({ dimension: w.name, operator: w.operator, values: [...w.values] })) + .sort((a, b) => (a.dimension + a.operator).localeCompare(b.dimension + b.operator)), + order: spec.orderBy.map((o) => `${o.ref}:${o.direction}`), + limit: spec.limit, + timeFrom: spec.timeConstraint?.start, + timeTo: spec.timeConstraint?.end, + grain: timeBucket?.grain, + }; +} diff --git a/src/analytics/contract/query-request.ts b/src/analytics/contract/query-request.ts new file mode 100644 index 0000000..4f0e9f4 --- /dev/null +++ b/src/analytics/contract/query-request.ts @@ -0,0 +1,489 @@ +/** + * src/analytics/contract/query-request.ts + * ======================================== + * BI-P016 — QUERY REQUEST CONTRACT. + * + * The canonical shape every SIAX product/application API speaks when it wants + * analytics: + * + * AnalyticsQueryRequest { dataset metrics[] dimensions[] filters[] + * timeRange orderBy limit format } + * + * BI-P016's hard rule: "The default product/application API must NOT accept + * arbitrary SQL." That is enforced structurally, not by a review convention — + * there is no field in this type that can carry SQL, and + * `parseAnalyticsQueryRequest` REJECTS unknown keys rather than ignoring them. + * A caller who adds `sql`, `where`, `having` or `expression` gets + * INVALID_REQUEST, not silent truncation; silent truncation is how an + * "unsupported" field becomes a supported one after the next refactor. + * + * Everything in this request is a NAME, resolved through a declared catalog + * (`QueryResolution`) before it can reach a compiler. Caller text therefore + * never becomes a SQL identifier and never becomes a SQL literal — the two + * ways injection happens. + * + * WHY THIS IS SEPARATE FROM `MetricQueryRequest` (engine/query-compiler.ts): + * that type is the ENGINE's internal, already-resolved, single-metric input, + * and it carries `tenant_id` because the engine sets it. This one is the + * CONSUMER-facing contract: it has no tenant field at all, because a consumer + * must never be able to name a tenant. INF0's Wave-2 hole was exactly a tenant + * read out of a request body; the fix that sticks is a request type in which + * the field does not exist. + */ +import { SiaxError } from '../../platform/errors'; + +// ── vocabulary ───────────────────────────────────────────────────────────── + +/** + * Filter operators. A CLOSED list: every one compiles to a fixed SQL shape + * with bound parameters. There is no "raw" or "expression" operator, and + * adding one would have to survive `filter-operators-are-closed` in + * tests/analytics/query-request-contract.test.ts. + */ +export const FILTER_OPERATORS = [ + 'eq', + 'ne', + 'in', + 'not_in', + 'lt', + 'lte', + 'gt', + 'gte', + 'contains', + 'is_null', + 'is_not_null', +] as const; +export type FilterOperator = (typeof FILTER_OPERATORS)[number]; + +/** Operators that take exactly one value. */ +const SINGLE_VALUE_OPERATORS: readonly FilterOperator[] = ['eq', 'ne', 'lt', 'lte', 'gt', 'gte', 'contains']; +/** Operators that take one-or-more values. */ +const MULTI_VALUE_OPERATORS: readonly FilterOperator[] = ['in', 'not_in']; +/** Operators that take NO value. Supplying one is a rejection, not a shrug. */ +const NO_VALUE_OPERATORS: readonly FilterOperator[] = ['is_null', 'is_not_null']; + +export const TIME_GRAINS = ['hour', 'day', 'week', 'month', 'quarter', 'year'] as const; +export type TimeGrain = (typeof TIME_GRAINS)[number]; + +export const ORDER_DIRECTIONS = ['asc', 'desc'] as const; +export type OrderDirection = (typeof ORDER_DIRECTIONS)[number]; + +/** Result encodings, matching `QueryResult.encoding` (BI-P002/BI-P005). */ +export const REQUEST_FORMATS = ['json', 'arrow_ipc'] as const; +export type RequestFormat = (typeof REQUEST_FORMATS)[number]; + +// ── the request ──────────────────────────────────────────────────────────── + +export interface AnalyticsFilter { + /** Caller-facing dimension NAME. Resolved through the catalog, never spliced. */ + dimension: string; + operator: FilterOperator; + /** Literal values. They travel as bound parameters; never as SQL text. */ + values?: string[]; +} + +export interface AnalyticsTimeRange { + /** + * Caller-facing time dimension name. Omitted means "the dataset's declared + * primary time dimension", which the resolution supplies — a consumer never + * has to know the physical column. + */ + dimension?: string; + /** ISO-8601 inclusive lower bound. */ + from?: string; + /** ISO-8601 EXCLUSIVE upper bound (half-open, so adjacent ranges never double count). */ + to?: string; + grain?: TimeGrain; +} + +export interface AnalyticsOrderBy { + /** + * A metric name or a dimension name that ALREADY APPEARS in this request. + * Ordering by something not selected is refused: it is both a correctness + * trap and the obvious place to smuggle an expression. + */ + ref: string; + direction: OrderDirection; +} + +/** BI-P016's canonical request, field-for-field. */ +export interface AnalyticsQueryRequest { + dataset: string; + metrics: string[]; + dimensions: string[]; + filters: AnalyticsFilter[]; + timeRange?: AnalyticsTimeRange; + orderBy?: AnalyticsOrderBy[]; + limit?: number; + format?: RequestFormat; +} + +/** The exact keys the contract accepts at the top level. */ +export const ANALYTICS_QUERY_REQUEST_KEYS = [ + 'dataset', + 'metrics', + 'dimensions', + 'filters', + 'timeRange', + 'orderBy', + 'limit', + 'format', +] as const; + +/** + * Keys a caller might reach for when they want to smuggle SQL. Listed + * explicitly so the rejection MESSAGE names the rule rather than saying + * "unknown key" — an integrator who tries `sql` should learn why, not guess. + * The unknown-key rejection below covers everything, listed or not. + */ +const SQL_SMELLING_KEYS = new Set([ + 'sql', + 'query', + 'rawSql', + 'raw_sql', + 'raw', + 'where', + 'having', + 'expression', + 'expr', + 'select', + 'from', + 'groupBy', + 'group_by', + 'sqlFragment', + 'unsafe', + 'tenant', + 'tenant_id', + 'tenantId', + 'project_id', + 'database', + 'catalog', + 'table', +]); + +const MAX_METRICS = 16; +const MAX_DIMENSIONS = 8; +const MAX_FILTERS = 32; +const MAX_FILTER_VALUES = 500; +const MAX_ORDER_BY = 8; +/** A name is a catalog key, not free text; keep it short and boring. */ +const MAX_NAME_LENGTH = 128; +/** A filter VALUE is data (it is bound, never spliced) but still bounded. */ +const MAX_VALUE_LENGTH = 4096; +export const DEFAULT_REQUEST_LIMIT = 1000; + +function invalid(detail: string): never { + throw new SiaxError('INVALID_REQUEST', '0pt.analytics', detail); +} + +function asObject(raw: unknown, what: string): Record { + if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) invalid(`${what} must be an object`); + return raw as Record; +} + +function asName(raw: unknown, what: string): string { + if (typeof raw !== 'string') invalid(`${what} must be a string`); + const v = raw.trim(); + if (!v) invalid(`${what} must not be empty`); + if (v.length > MAX_NAME_LENGTH) invalid(`${what} exceeds ${MAX_NAME_LENGTH} characters`); + return v; +} + +function rejectUnknownKeys(obj: Record, allowed: readonly string[], what: string): void { + for (const key of Object.keys(obj)) { + if (allowed.includes(key)) continue; + if (SQL_SMELLING_KEYS.has(key)) { + invalid( + `"${key}" is not part of the analytics query contract — the product API does not accept SQL, ` + + `catalogs, or tenant selection (BI-P016)`, + ); + } + invalid(`unknown field "${key}" in ${what}`); + } +} + +/** + * Parse and VALIDATE an untrusted request body into the canonical contract. + * + * Fail-closed at every branch: an unparseable field is a rejection, never a + * default. The only defaulting this function does is `filters: []`, + * `dimensions: []` and `limit`, and each of those defaults is strictly + * narrower than any value a caller could have supplied. + */ +export function parseAnalyticsQueryRequest(raw: unknown): AnalyticsQueryRequest { + const obj = asObject(raw, 'analytics query request'); + rejectUnknownKeys(obj, ANALYTICS_QUERY_REQUEST_KEYS, 'analytics query request'); + + const dataset = asName(obj.dataset, 'dataset'); + + if (!Array.isArray(obj.metrics)) invalid('metrics must be an array'); + if (obj.metrics.length === 0) invalid('at least one metric is required'); + if (obj.metrics.length > MAX_METRICS) invalid(`at most ${MAX_METRICS} metrics per request`); + const metrics = obj.metrics.map((m, i) => asName(m, `metrics[${i}]`)); + if (new Set(metrics).size !== metrics.length) invalid('metrics contains duplicates'); + + const rawDimensions = obj.dimensions ?? []; + if (!Array.isArray(rawDimensions)) invalid('dimensions must be an array'); + if (rawDimensions.length > MAX_DIMENSIONS) invalid(`at most ${MAX_DIMENSIONS} dimensions per request`); + const dimensions = rawDimensions.map((d, i) => asName(d, `dimensions[${i}]`)); + if (new Set(dimensions).size !== dimensions.length) invalid('dimensions contains duplicates'); + + const rawFilters = obj.filters ?? []; + if (!Array.isArray(rawFilters)) invalid('filters must be an array'); + if (rawFilters.length > MAX_FILTERS) invalid(`at most ${MAX_FILTERS} filters per request`); + const filters = rawFilters.map((f, i) => parseFilter(f, i)); + + const timeRange = obj.timeRange === undefined ? undefined : parseTimeRange(obj.timeRange); + + const rawOrderBy = obj.orderBy ?? []; + if (!Array.isArray(rawOrderBy)) invalid('orderBy must be an array'); + if (rawOrderBy.length > MAX_ORDER_BY) invalid(`at most ${MAX_ORDER_BY} orderBy entries`); + const orderBy = rawOrderBy.map((o, i) => parseOrderBy(o, i)); + const selectable = new Set([...metrics, ...dimensions]); + for (const o of orderBy) { + if (!selectable.has(o.ref)) { + invalid(`orderBy "${o.ref}" is neither a requested metric nor a requested dimension`); + } + } + + let limit = DEFAULT_REQUEST_LIMIT; + if (obj.limit !== undefined) { + if (typeof obj.limit !== 'number' || !Number.isFinite(obj.limit)) + invalid('limit must be a finite number'); + if (!Number.isInteger(obj.limit)) invalid('limit must be an integer'); + if (obj.limit < 1) invalid('limit must be >= 1'); + limit = obj.limit; + } + + let format: RequestFormat = 'json'; + if (obj.format !== undefined) { + if (typeof obj.format !== 'string' || !(REQUEST_FORMATS as readonly string[]).includes(obj.format)) { + invalid(`format must be one of ${REQUEST_FORMATS.join(', ')}`); + } + format = obj.format as RequestFormat; + } + + return { dataset, metrics, dimensions, filters, timeRange, orderBy, limit, format }; +} + +function parseFilter(raw: unknown, index: number): AnalyticsFilter { + const obj = asObject(raw, `filters[${index}]`); + rejectUnknownKeys(obj, ['dimension', 'operator', 'values'], `filters[${index}]`); + const dimension = asName(obj.dimension, `filters[${index}].dimension`); + if (typeof obj.operator !== 'string' || !(FILTER_OPERATORS as readonly string[]).includes(obj.operator)) { + invalid(`filters[${index}].operator must be one of ${FILTER_OPERATORS.join(', ')}`); + } + const operator = obj.operator as FilterOperator; + + if (NO_VALUE_OPERATORS.includes(operator)) { + if (obj.values !== undefined) invalid(`filters[${index}].operator "${operator}" takes no values`); + return { dimension, operator }; + } + + if (!Array.isArray(obj.values)) invalid(`filters[${index}].values must be an array`); + if (obj.values.length === 0) invalid(`filters[${index}].values must not be empty`); + if (obj.values.length > MAX_FILTER_VALUES) { + invalid(`filters[${index}].values exceeds ${MAX_FILTER_VALUES} entries`); + } + if (SINGLE_VALUE_OPERATORS.includes(operator) && obj.values.length !== 1) { + invalid(`filters[${index}].operator "${operator}" takes exactly one value`); + } + if (!MULTI_VALUE_OPERATORS.includes(operator) && !SINGLE_VALUE_OPERATORS.includes(operator)) { + invalid(`filters[${index}].operator "${operator}" is not a value operator`); + } + const values = obj.values.map((v, i) => { + if (typeof v !== 'string') invalid(`filters[${index}].values[${i}] must be a string`); + if (v.length > MAX_VALUE_LENGTH) + invalid(`filters[${index}].values[${i}] exceeds ${MAX_VALUE_LENGTH} characters`); + return v; + }); + return { dimension, operator, values }; +} + +function parseTimeRange(raw: unknown): AnalyticsTimeRange { + const obj = asObject(raw, 'timeRange'); + rejectUnknownKeys(obj, ['dimension', 'from', 'to', 'grain'], 'timeRange'); + const out: AnalyticsTimeRange = {}; + if (obj.dimension !== undefined) out.dimension = asName(obj.dimension, 'timeRange.dimension'); + if (obj.from !== undefined) out.from = asIsoInstant(obj.from, 'timeRange.from'); + if (obj.to !== undefined) out.to = asIsoInstant(obj.to, 'timeRange.to'); + if (obj.grain !== undefined) { + if (typeof obj.grain !== 'string' || !(TIME_GRAINS as readonly string[]).includes(obj.grain)) { + invalid(`timeRange.grain must be one of ${TIME_GRAINS.join(', ')}`); + } + out.grain = obj.grain as TimeGrain; + } + if (out.from && out.to && Date.parse(out.from) >= Date.parse(out.to)) { + invalid('timeRange.from must be strictly before timeRange.to'); + } + return out; +} + +/** + * A timestamp is validated as a real instant, not merely as "a string that + * gets bound". It is bound as a parameter either way, so this is not the + * injection defence — it is the defence against a nonsense range silently + * producing an empty answer that a dashboard renders as "zero sales". + */ +function asIsoInstant(raw: unknown, what: string): string { + if (typeof raw !== 'string') invalid(`${what} must be an ISO-8601 string`); + const v = raw.trim(); + if (!/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?)?$/.test(v)) { + invalid(`${what} is not an ISO-8601 timestamp`); + } + if (Number.isNaN(Date.parse(v))) invalid(`${what} is not a valid timestamp`); + return v; +} + +function parseOrderBy(raw: unknown, index: number): AnalyticsOrderBy { + const obj = asObject(raw, `orderBy[${index}]`); + rejectUnknownKeys(obj, ['ref', 'direction'], `orderBy[${index}]`); + const ref = asName(obj.ref, `orderBy[${index}].ref`); + if (typeof obj.direction !== 'string' || !(ORDER_DIRECTIONS as readonly string[]).includes(obj.direction)) { + invalid(`orderBy[${index}].direction must be one of ${ORDER_DIRECTIONS.join(', ')}`); + } + return { ref, direction: obj.direction as OrderDirection }; +} + +// ── resolution: names -> declared catalog entries ────────────────────────── + +/** + * What a metric NAME resolves to. Supplied from `MetricDefinition` rows + * (BI-P002/BI-P028); the compilers never invent one. + */ +export interface ResolvedMetric { + name: string; + metric_id: string; + /** The `metric` key stored in the analytics event table. */ + event_metric_key: string; + aggregation: 'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct'; + /** Dimension names this metric may legitimately be sliced by. */ + allowed_dimensions: readonly string[]; + unit?: string; +} + +/** What a dimension NAME resolves to. Supplied from `DimensionDefinition` rows. */ +export interface ResolvedDimension { + name: string; + dimension_id: string; + /** Physical key inside `dim_names`. Validated as an identifier downstream. */ + field_name: string; +} + +/** + * The declared surface for ONE dataset, for ONE tenant. A compiler is handed + * this; it cannot reach past it. An unresolvable name is a rejection. + */ +export interface QueryResolution { + dataset_id: string; + /** Semantic model version this resolution came from — part of the cache key (BI-P020). */ + semantic_model_version?: number; + metric(name: string): ResolvedMetric | undefined; + dimension(name: string): ResolvedDimension | undefined; + /** Physical time dimension used when `timeRange.dimension` is omitted. */ + defaultTimeDimension?: string; +} + +export function queryResolutionFrom(args: { + dataset_id: string; + metrics: readonly ResolvedMetric[]; + dimensions: readonly ResolvedDimension[]; + semantic_model_version?: number; + defaultTimeDimension?: string; +}): QueryResolution { + const metricMap = new Map(args.metrics.map((m) => [m.name, m])); + const dimMap = new Map(args.dimensions.map((d) => [d.name, d])); + return { + dataset_id: args.dataset_id, + semantic_model_version: args.semantic_model_version, + defaultTimeDimension: args.defaultTimeDimension, + // Map lookups: "__proto__" / "constructor" resolve to undefined, as they must. + metric: (name) => metricMap.get(name), + dimension: (name) => dimMap.get(name), + }; +} + +/** + * Resolve every name in a request, or refuse the request. + * + * This is the single place where "a caller said X" becomes "the catalog + * declares Y". Both compile targets (ClickHouse and semantic) consume the + * RESOLVED form, which is why BI-P016's DoD holds: the consumer writes one + * request and neither target sees consumer text. + */ +export interface ResolvedQuery { + request: AnalyticsQueryRequest; + dataset_id: string; + metrics: ResolvedMetric[]; + dimensions: ResolvedDimension[]; + filters: Array<{ filter: AnalyticsFilter; dimension: ResolvedDimension }>; + timeDimension?: string; + semantic_model_version?: number; +} + +export function resolveAnalyticsQuery( + request: AnalyticsQueryRequest, + resolution: QueryResolution, +): ResolvedQuery { + if (request.dataset !== resolution.dataset_id) { + // The resolution is built FOR a dataset the caller was authorised to read + // (BI-P006 grants). A mismatch means the caller is asking about something + // else entirely, and answering from this resolution would be a leak. + throw new SiaxError( + 'AUTHORIZATION_DENIED', + '0pt.analytics', + 'requested dataset does not match the authorised resolution', + ); + } + const metrics = request.metrics.map((name) => { + const m = resolution.metric(name); + if (!m) invalid(`unknown metric "${name}" for this dataset`); + return m; + }); + const dimensions = request.dimensions.map((name) => { + const d = resolution.dimension(name); + if (!d) invalid(`unknown dimension "${name}" for this dataset`); + return d; + }); + // Every requested dimension must be legitimate for EVERY requested metric. + // Slicing a metric by a dimension its definition does not allow is how a + // "harmless" grouping turns into an unintended disclosure. + for (const m of metrics) { + for (const d of dimensions) { + if (!m.allowed_dimensions.includes(d.name)) { + throw new SiaxError( + 'AUTHORIZATION_DENIED', + '0pt.analytics', + `metric "${m.name}" may not be sliced by dimension "${d.name}"`, + ); + } + } + } + const filters = request.filters.map((f) => { + const d = resolution.dimension(f.dimension); + if (!d) invalid(`unknown filter dimension "${f.dimension}"`); + return { filter: f, dimension: d }; + }); + let timeDimension: string | undefined; + if (request.timeRange) { + if (request.timeRange.dimension) { + const d = resolution.dimension(request.timeRange.dimension); + if (!d) invalid(`unknown time dimension "${request.timeRange.dimension}"`); + timeDimension = d.field_name; + } else { + timeDimension = resolution.defaultTimeDimension; + if ((request.timeRange.from || request.timeRange.to) && !timeDimension) { + invalid('dataset declares no default time dimension; timeRange.dimension is required'); + } + } + } + return { + request, + dataset_id: resolution.dataset_id, + metrics, + dimensions, + filters, + timeDimension, + semantic_model_version: resolution.semantic_model_version, + }; +} diff --git a/tests/analytics/query-request-contract.test.ts b/tests/analytics/query-request-contract.test.ts new file mode 100644 index 0000000..bd7cc6f --- /dev/null +++ b/tests/analytics/query-request-contract.test.ts @@ -0,0 +1,554 @@ +/** + * tests/analytics/query-request-contract.test.ts + * ============================================== + * BI-P016 — QUERY REQUEST CONTRACT. + * + * Two claims are under test, and both are stated so they can FAIL: + * + * 1. "The default product/application API must NOT accept arbitrary SQL." + * Tested by feeding the parser every field name a caller would reach for + * to smuggle SQL and asserting a rejection — not by asserting the type + * lacks the field, which a compiler already guarantees and a JSON body + * ignores. + * + * 2. "Same request can compile to ClickHouse/semantic engine without + * consumer rewrite." Tested by projecting BOTH compiled artefacts onto a + * comparable shape and demanding equality. The ClickHouse side of that + * projection is obtained by PARSING the emitted SQL and its bound + * parameters here in the test — not by trusting a field the compiler + * helpfully returned. A compiler that silently drops a filter therefore + * fails this test instead of passing it. + */ +import { describe, expect, it } from 'vitest'; +import { SiaxError } from '@/src/platform/errors'; +import { + ANALYTICS_QUERY_REQUEST_KEYS, + FILTER_OPERATORS, + parseAnalyticsQueryRequest, + queryResolutionFrom, + resolveAnalyticsQuery, + type AnalyticsQueryRequest, + type FilterOperator, + type ResolvedDimension, + type ResolvedMetric, +} from '@/src/analytics/contract/query-request'; +import { + compileRequestToClickHouse, + type CompiledAnalyticsQuery, +} from '@/src/analytics/contract/compile-clickhouse'; +import { + compileRequestToSemantic, + shapeOfSemanticSpec, + type QueryShape, +} from '@/src/analytics/contract/compile-semantic'; +import { FORCED_TENANT_PREDICATE } from '@/src/analytics/engine/query-compiler'; + +// ── the declared catalog under test ──────────────────────────────────────── + +const METRICS: ResolvedMetric[] = [ + { + name: 'orders', + metric_id: 'm_orders', + event_metric_key: 'order_count', + aggregation: 'count', + allowed_dimensions: ['country', 'channel', 'segment'], + }, + { + name: 'revenue', + metric_id: 'm_revenue', + event_metric_key: 'revenue_sek', + aggregation: 'sum', + allowed_dimensions: ['country', 'channel', 'segment'], + unit: 'SEK', + }, + { + name: 'restricted', + metric_id: 'm_restricted', + event_metric_key: 'restricted_measure', + aggregation: 'sum', + // Deliberately NOT sliceable by `segment`. + allowed_dimensions: ['country'], + }, +]; + +const DIMENSIONS: ResolvedDimension[] = [ + { name: 'country', dimension_id: 'd_country', field_name: 'country_code' }, + { name: 'channel', dimension_id: 'd_channel', field_name: 'sales_channel' }, + { name: 'segment', dimension_id: 'd_segment', field_name: 'customer_segment' }, +]; + +const resolution = queryResolutionFrom({ + dataset_id: 'ds_sales', + metrics: METRICS, + dimensions: DIMENSIONS, + semantic_model_version: 7, + defaultTimeDimension: 'event_time', +}); + +const FIELD_TO_NAME = new Map(DIMENSIONS.map((d) => [d.field_name, d.name])); +const KEY_TO_METRIC = new Map(METRICS.map((m) => [m.event_metric_key, m.name])); + +function compile(req: AnalyticsQueryRequest): CompiledAnalyticsQuery { + return compileRequestToClickHouse(resolveAnalyticsQuery(req, resolution), { + tenant_id: 't_alpha', + project_id: 'p_main', + database: 'opt_analytics', + maxResultRows: 10_000, + }); +} + +// ── independent parser: SQL text + bound params -> comparable shape ──────── + +/** Split a WHERE clause on top-level " AND " (parenthesised lists survive). */ +function splitConditions(where: string): string[] { + const out: string[] = []; + let depth = 0; + let current = ''; + for (let i = 0; i < where.length; i += 1) { + const c = where[i]; + if (c === '(') depth += 1; + if (c === ')') depth -= 1; + if (depth === 0 && where.startsWith(' AND ', i)) { + out.push(current); + current = ''; + i += 4; + continue; + } + current += c; + } + if (current) out.push(current); + return out; +} + +const OP_SYMBOL: Record = { + '=': 'eq', + '!=': 'ne', + '<': 'lt', + '<=': 'lte', + '>': 'gt', + '>=': 'gte', +}; + +/** + * Reconstruct the query's meaning from the artefact the engine would actually + * send. Anything the compiler failed to emit is invisible here, which is the + * point. + */ +function shapeOfCompiledSql(c: CompiledAnalyticsQuery): QueryShape { + const p = (key: string): string => { + const v = c.params[`param_${key}`]; + if (v === undefined) throw new Error(`compiled SQL references unbound parameter ${key}`); + return v; + }; + const whereMatch = /\sWHERE\s(.*?)(?:\sGROUP BY\s|\sORDER BY\s|\sLIMIT\s)/.exec(c.sql); + if (!whereMatch) throw new Error('compiled SQL has no WHERE clause'); + const conditions = splitConditions(whereMatch[1]); + + const filters: QueryShape['filters'] = []; + let timeFrom: string | undefined; + let timeTo: string | undefined; + + for (const cond of conditions) { + if (cond === FORCED_TENANT_PREDICATE) continue; + if (/^project_id = \{project:String\}$/.test(cond)) continue; + if (/^dataset_id = \{dataset:String\}$/.test(cond)) continue; + if (/^metric IN \(/.test(cond)) continue; + + let m = /^\w+ >= parseDateTime64BestEffort\(\{fromTime:String\}\)$/.exec(cond); + if (m) { + timeFrom = p('fromTime'); + continue; + } + m = /^\w+ < parseDateTime64BestEffort\(\{toTime:String\}\)$/.exec(cond); + if (m) { + timeTo = p('toTime'); + continue; + } + m = /^position\(dim_values\[indexOf\(dim_names, \{(fn\d+):String\}\)\], \{(fv\d+):String\}\) > 0$/.exec( + cond, + ); + if (m) { + filters.push({ dimension: dimNameFor(p(m[1])), operator: 'contains', values: [p(m[2])] }); + continue; + } + m = /^(NOT )?has\(dim_names, \{(fn\d+):String\}\)$/.exec(cond); + if (m) { + filters.push({ + dimension: dimNameFor(p(m[2])), + operator: m[1] ? 'is_null' : 'is_not_null', + values: [], + }); + continue; + } + m = /^dim_values\[indexOf\(dim_names, \{(fn\d+):String\}\)\] (NOT IN|IN) \((.+)\)$/.exec(cond); + if (m) { + const keys = m[3].split(', ').map((t) => /^\{(fv\d+_\d+):String\}$/.exec(t)?.[1]); + if (keys.some((k) => !k)) throw new Error(`IN list contains a non-parameter token: ${m[3]}`); + filters.push({ + dimension: dimNameFor(p(m[1])), + operator: m[2] === 'NOT IN' ? 'not_in' : 'in', + values: keys.map((k) => p(k as string)), + }); + continue; + } + m = /^dim_values\[indexOf\(dim_names, \{(fn\d+):String\}\)\] (=|!=|<=|>=|<|>) \{(fv\d+):String\}$/.exec( + cond, + ); + if (m) { + filters.push({ dimension: dimNameFor(p(m[1])), operator: OP_SYMBOL[m[2]], values: [p(m[3])] }); + continue; + } + throw new Error(`unrecognised compiled condition (possible unbound SQL text): ${cond}`); + } + + const selectMatch = /^SELECT (.*?) FROM /.exec(c.sql); + if (!selectMatch) throw new Error('compiled SQL has no SELECT list'); + const metricKeys = [...selectMatch[1].matchAll(/\{(m\d+):String\}/g)].map((mm) => p(mm[1])); + const dimKeys = [...selectMatch[1].matchAll(/\{(d\d+):String\}/g)].map((mm) => p(mm[1])); + const grainMatch = /toStartOf(\w+)\(/.exec(selectMatch[1]); + + const orderMatch = /\sORDER BY\s(.*?)\sLIMIT\s/.exec(c.sql); + const order = orderMatch + ? orderMatch[1].split(', ').map((tok) => { + const [alias, dir] = tok.split(' '); + const name = c.metricAliases[alias] ?? c.dimensionAliases[alias]; + if (!name) throw new Error(`ORDER BY references unknown alias ${alias}`); + return `${name}:${dir.toLowerCase()}`; + }) + : []; + + const limitMatch = /\sLIMIT (\d+) FORMAT JSON$/.exec(c.sql); + if (!limitMatch) throw new Error('compiled SQL has no LIMIT'); + + return { + dataset_id: p('dataset'), + metrics: metricKeys.map((k) => KEY_TO_METRIC.get(k) ?? k).sort(), + dimensions: dimKeys.map((k) => FIELD_TO_NAME.get(k) ?? k).sort(), + filters: filters.sort((a, b) => (a.dimension + a.operator).localeCompare(b.dimension + b.operator)), + order, + limit: Number(limitMatch[1]), + timeFrom, + timeTo, + grain: grainMatch ? (grainMatch[1].toLowerCase() as QueryShape['grain']) : undefined, + }; +} + +function dimNameFor(field: string): string { + const name = FIELD_TO_NAME.get(field); + if (!name) throw new Error(`compiled SQL bound an unknown physical dimension "${field}"`); + return name; +} + +// ── 1. the API does not accept SQL ───────────────────────────────────────── + +describe('BI-P016 — the product API accepts no SQL', () => { + const base = { dataset: 'ds_sales', metrics: ['orders'] }; + + const smuggling = [ + 'sql', + 'query', + 'rawSql', + 'raw_sql', + 'raw', + 'where', + 'having', + 'expression', + 'expr', + 'select', + 'from', + 'groupBy', + 'group_by', + 'unsafe', + ]; + + it.each(smuggling)('rejects a request carrying a %s field', (key) => { + expect(() => parseAnalyticsQueryRequest({ ...base, [key]: 'SELECT 1' })).toThrowError(SiaxError); + try { + parseAnalyticsQueryRequest({ ...base, [key]: 'SELECT 1' }); + } catch (e) { + expect((e as SiaxError).code).toBe('INVALID_REQUEST'); + } + }); + + // The INF0 Wave-2 lesson: a tenant read out of a request body. The contract + // must not merely IGNORE such a field; ignoring it is what lets a later + // refactor start honouring it. + it.each(['tenant', 'tenant_id', 'tenantId', 'project_id', 'database', 'catalog', 'table'])( + 'rejects caller-supplied %s (tenant/catalog selection is never a request field)', + (key) => { + expect(() => parseAnalyticsQueryRequest({ ...base, [key]: 't_beta' })).toThrowError(SiaxError); + }, + ); + + it('rejects ANY unknown key, not just the ones on the smell list', () => { + expect(() => parseAnalyticsQueryRequest({ ...base, somethingNewNextQuarter: 1 })).toThrowError(SiaxError); + }); + + it('accepts exactly the eight BI-P016 fields and no more', () => { + expect([...ANALYTICS_QUERY_REQUEST_KEYS]).toEqual([ + 'dataset', + 'metrics', + 'dimensions', + 'filters', + 'timeRange', + 'orderBy', + 'limit', + 'format', + ]); + }); + + it('rejects SQL smuggled into a nested filter object', () => { + expect(() => + parseAnalyticsQueryRequest({ + ...base, + filters: [{ dimension: 'country', operator: 'eq', values: ['SE'], sql: 'OR 1=1' }], + }), + ).toThrowError(SiaxError); + }); + + it('keeps the filter operator set closed', () => { + expect([...FILTER_OPERATORS]).toEqual([ + 'eq', + 'ne', + 'in', + 'not_in', + 'lt', + 'lte', + 'gt', + 'gte', + 'contains', + 'is_null', + 'is_not_null', + ]); + expect(() => + parseAnalyticsQueryRequest({ + ...base, + filters: [{ dimension: 'country', operator: 'raw', values: ['x'] }], + }), + ).toThrowError(SiaxError); + }); + + it('refuses an orderBy that is not selected (the obvious expression smuggling slot)', () => { + expect(() => + parseAnalyticsQueryRequest({ ...base, orderBy: [{ ref: '(SELECT 1)', direction: 'asc' }] }), + ).toThrowError(SiaxError); + }); + + it('refuses a metric the catalog does not declare', () => { + const req = parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['orders OR 1=1'] }); + expect(() => resolveAnalyticsQuery(req, resolution)).toThrowError(SiaxError); + }); + + it('refuses slicing a metric by a dimension its definition disallows', () => { + const req = parseAnalyticsQueryRequest({ + dataset: 'ds_sales', + metrics: ['restricted'], + dimensions: ['segment'], + }); + try { + resolveAnalyticsQuery(req, resolution); + throw new Error('expected a rejection'); + } catch (e) { + expect((e as SiaxError).code).toBe('AUTHORIZATION_DENIED'); + } + }); + + it('refuses a dataset that is not the authorised one', () => { + const req = parseAnalyticsQueryRequest({ dataset: 'ds_other', metrics: ['orders'] }); + try { + resolveAnalyticsQuery(req, resolution); + throw new Error('expected a rejection'); + } catch (e) { + expect((e as SiaxError).code).toBe('AUTHORIZATION_DENIED'); + } + }); + + it('rejects a reversed time range instead of silently returning zero rows', () => { + expect(() => + parseAnalyticsQueryRequest({ ...base, timeRange: { from: '2026-02-01', to: '2026-01-01' } }), + ).toThrowError(SiaxError); + }); +}); + +// ── 2. one request, two targets, same meaning ────────────────────────────── + +describe('BI-P016 DoD — one request compiles to ClickHouse and to the semantic engine', () => { + const requests: Array<[string, unknown]> = [ + ['metric only', { dataset: 'ds_sales', metrics: ['orders'] }], + [ + 'two metrics, two dimensions', + { dataset: 'ds_sales', metrics: ['orders', 'revenue'], dimensions: ['country', 'channel'] }, + ], + [ + 'filters of every value operator', + { + dataset: 'ds_sales', + metrics: ['revenue'], + dimensions: ['country'], + filters: [ + { dimension: 'country', operator: 'eq', values: ['SE'] }, + { dimension: 'channel', operator: 'in', values: ['web', 'retail'] }, + { dimension: 'segment', operator: 'not_in', values: ['test'] }, + { dimension: 'channel', operator: 'contains', values: ['we'] }, + ], + }, + ], + [ + 'time range with grain and ordering', + { + dataset: 'ds_sales', + metrics: ['revenue'], + dimensions: ['country'], + timeRange: { from: '2026-01-01T00:00:00Z', to: '2026-02-01T00:00:00Z', grain: 'day' }, + orderBy: [{ ref: 'revenue', direction: 'desc' }], + limit: 50, + }, + ], + [ + 'presence filters', + { + dataset: 'ds_sales', + metrics: ['orders'], + filters: [ + { dimension: 'segment', operator: 'is_null' }, + { dimension: 'channel', operator: 'is_not_null' }, + ], + }, + ], + ]; + + it.each(requests)('%s — both targets agree', (_label, raw) => { + const req = parseAnalyticsQueryRequest(raw); + const resolved = resolveAnalyticsQuery(req, resolution); + const ch = compileRequestToClickHouse(resolved, { + tenant_id: 't_alpha', + project_id: 'p_main', + database: 'opt_analytics', + maxResultRows: 10_000, + }); + const sem = compileRequestToSemantic(resolved); + + const fromSql = shapeOfCompiledSql(ch); + const fromSemantic = shapeOfSemanticSpec(sem); + + expect(fromSql.dataset_id).toBe(fromSemantic.dataset_id); + expect(fromSql.metrics).toEqual(fromSemantic.metrics); + expect(fromSql.dimensions).toEqual(fromSemantic.dimensions); + expect(fromSql.filters).toEqual(fromSemantic.filters); + expect(fromSql.order).toEqual(fromSemantic.order); + expect(fromSql.limit).toBe(fromSemantic.limit); + expect(fromSql.timeFrom).toBe(fromSemantic.timeFrom); + expect(fromSql.timeTo).toBe(fromSemantic.timeTo); + expect(fromSql.grain).toBe(fromSemantic.grain); + }); + + it('carries the canonical metric_id into the semantic spec so the engine is replaceable', () => { + const req = parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['revenue'] }); + const spec = compileRequestToSemantic(resolveAnalyticsQuery(req, resolution)); + expect(spec.metrics[0].metric_id).toBe('m_revenue'); + expect(spec.semantic_model_version).toBe(7); + }); + + it('never puts a SQL predicate string in the semantic spec', () => { + const req = parseAnalyticsQueryRequest({ + dataset: 'ds_sales', + metrics: ['orders'], + filters: [{ dimension: 'country', operator: 'eq', values: ["SE' OR '1'='1"] }], + }); + const spec = compileRequestToSemantic(resolveAnalyticsQuery(req, resolution)); + // The hostile value survives as DATA — structured, not concatenated. + expect(spec.where[0].values).toEqual(["SE' OR '1'='1"]); + expect(JSON.stringify(spec)).not.toMatch(/SELECT|WHERE\s/i); + }); +}); + +// ── 3. tenant forcing survives every request shape ───────────────────────── + +describe('BI-P011 forced tenant predicate survives the BI-P016 contract', () => { + it.each(requests())('compiled SQL forces the tenant predicate first: %s', (_label, raw) => { + const c = compile(parseAnalyticsQueryRequest(raw)); + const where = /\sWHERE\s(.*?)(?:\sGROUP BY\s|\sORDER BY\s|\sLIMIT\s)/.exec(c.sql); + expect(where).not.toBeNull(); + expect(splitConditions((where as RegExpExecArray)[1])[0]).toBe(FORCED_TENANT_PREDICATE); + expect(c.params.param_tenant).toBe('t_alpha'); + }); + + it('refuses to compile with a blank tenant rather than emitting no predicate', () => { + const resolved = resolveAnalyticsQuery( + parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['orders'] }), + resolution, + ); + for (const blank of ['', ' ']) { + expect(() => + compileRequestToClickHouse(resolved, { + tenant_id: blank, + database: 'opt_analytics', + maxResultRows: 100, + }), + ).toThrowError(SiaxError); + } + }); + + it('puts no caller-supplied value anywhere in the SQL text', () => { + const hostile = "'; DROP TABLE opt_analytics_event; --"; + const c = compile( + parseAnalyticsQueryRequest({ + dataset: 'ds_sales', + metrics: ['orders'], + filters: [{ dimension: 'country', operator: 'eq', values: [hostile] }], + }), + ); + expect(c.sql).not.toContain(hostile); + expect(c.sql).not.toContain('DROP'); + expect(Object.values(c.params)).toContain(hostile); + }); + + it('clamps the limit down to the governance ceiling and never up', () => { + const resolved = resolveAnalyticsQuery( + parseAnalyticsQueryRequest({ dataset: 'ds_sales', metrics: ['orders'], limit: 1_000_000 }), + resolution, + ); + const c = compileRequestToClickHouse(resolved, { + tenant_id: 't_alpha', + database: 'opt_analytics', + maxResultRows: 500, + }); + expect(c.effectiveLimit).toBe(500); + expect(c.sql).toContain('LIMIT 500'); + }); +}); + +function requests(): Array<[string, unknown]> { + return [ + ['bare', { dataset: 'ds_sales', metrics: ['orders'] }], + ['grouped', { dataset: 'ds_sales', metrics: ['orders'], dimensions: ['country'] }], + [ + 'filtered', + { + dataset: 'ds_sales', + metrics: ['orders'], + filters: [{ dimension: 'country', operator: 'in', values: ['SE', 'NO'] }], + }, + ], + [ + 'time-bucketed', + { dataset: 'ds_sales', metrics: ['revenue'], timeRange: { from: '2026-01-01', grain: 'month' } }, + ], + [ + 'everything at once', + { + dataset: 'ds_sales', + metrics: ['orders', 'revenue'], + dimensions: ['country', 'channel'], + filters: [ + { dimension: 'segment', operator: 'ne', values: ['internal'] }, + { dimension: 'channel', operator: 'is_not_null' }, + ], + timeRange: { from: '2026-01-01', to: '2026-03-01', grain: 'week' }, + orderBy: [{ ref: 'revenue', direction: 'desc' }], + limit: 25, + format: 'arrow_ipc', + }, + ], + ]; +}