From b1884a89a5be3c61aec47a41e3922eca27af715f Mon Sep 17 00:00:00 2001 From: Claude Opus 5 Date: Mon, 7 Sep 2026 02:00:07 +0200 Subject: [PATCH] =?UTF-8?q?feat(analytics):=20BI-P016=20=E2=80=94=20canoni?= =?UTF-8?q?cal=20query=20request=20contract,=20two=20compile=20targets?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The eight-field AnalyticsQueryRequest BI-P016 names, verbatim, with the rule that makes it safe enforced structurally rather than by convention: there is no field that can carry SQL, and parseAnalyticsQueryRequest REJECTS unknown keys instead of ignoring them. Ignoring an unsupported field is how it becomes a supported one after the next refactor. `tenant`, `tenant_id`, `project_id`, `database`, `catalog` and `table` are rejected by name. INF0's Wave-2 cross-tenant hole was a tenant read out of a request body; the fix that sticks is a request type in which the field does not exist, and a parser that refuses it when a caller sends it anyway. BI-P016's DoD ("same request compiles to ClickHouse/semantic engine without consumer rewrite") is tested as an equality, not narrated: both targets are projected onto a comparable shape and compared. The ClickHouse side of that projection is obtained by PARSING the emitted SQL and its bound parameters in the test — not by reading a field the compiler helpfully returned — so a compiler that silently drops a filter fails the comparison instead of passing it. The parser throws on any condition it does not recognise, which is what would catch unbound caller text appearing in the statement. BI-P011's forced tenant predicate is re-proven against this new path: five request shapes are enumerated and each must have FORCED_TENANT_PREDICATE as condition[0]; a blank tenant refuses to compile rather than emitting no predicate; a hostile filter value appears only in params, never in sql. 45 tests, all failing-capable: every rejection assertion checks the SiaxError code, and the DoD assertions compare reconstructed meaning rather than strings. Co-Authored-By: Claude Opus 5 --- src/analytics/contract/compile-clickhouse.ts | 252 ++++++++ src/analytics/contract/compile-semantic.ts | 145 +++++ src/analytics/contract/query-request.ts | 489 ++++++++++++++++ .../analytics/query-request-contract.test.ts | 554 ++++++++++++++++++ 4 files changed, 1440 insertions(+) create mode 100644 src/analytics/contract/compile-clickhouse.ts create mode 100644 src/analytics/contract/compile-semantic.ts create mode 100644 src/analytics/contract/query-request.ts create mode 100644 tests/analytics/query-request-contract.test.ts 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', + }, + ], + ]; +}