@quereus/quereus 0.1.0

package/src/planner/building/schema-resolution.ts

@@ -0,0 +1,176 @@
+import type { PlanningContext, SchemaDependency } from '../planning-context.js';
+import type { TableSchema } from '../../schema/table.js';
+import type { FunctionSchema } from '../../schema/function.js';
+import type { VirtualTableModule } from '../../vtab/module.js';
+import type { CollationFunction } from '../../util/comparison.js';
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+import { createLogger } from '../../common/logger.js';
+
+const log = createLogger('planner:schema-resolution');
+
+/**
+ * Resolves a table schema at build time and records the dependency.
+ */
+export function resolveTableSchema(
+	ctx: PlanningContext,
+	tableName: string,
+	schemaName?: string
+): TableSchema {
+	const resolvedSchemaName = schemaName || ctx.db.schemaManager.getCurrentSchemaName();
+	const cacheKey = `table:${resolvedSchemaName}:${tableName}`;
+
+	// Check cache first
+	const cached = ctx.schemaCache.get(cacheKey);
+	if (cached) {
+		log('Using cached table schema: %s.%s', resolvedSchemaName, tableName);
+		return cached as TableSchema;
+	}
+
+	// Resolve table schema
+	const tableSchema = ctx.schemaManager.findTable(tableName, resolvedSchemaName);
+	if (!tableSchema) {
+		throw new QuereusError(
+			`Table not found: ${resolvedSchemaName}.${tableName}`,
+			StatusCode.ERROR
+		);
+	}
+
+	// Record dependency
+	const dependency: SchemaDependency = {
+		type: 'table',
+		schemaName: tableSchema.schemaName,
+		objectName: tableSchema.name
+	};
+	ctx.schemaDependencies.recordDependency(dependency, tableSchema);
+
+	// Cache result
+	ctx.schemaCache.set(cacheKey, tableSchema);
+
+	log('Resolved table schema: %s.%s', tableSchema.schemaName, tableSchema.name);
+	return tableSchema;
+}
+
+/**
+ * Resolves a function schema at build time and records the dependency.
+ */
+export function resolveFunctionSchema(
+	ctx: PlanningContext,
+	funcName: string,
+	numArgs: number
+): FunctionSchema {
+	const cacheKey = `function:${funcName}/${numArgs}`;
+
+	// Check cache first
+	const cached = ctx.schemaCache.get(cacheKey);
+	if (cached) {
+		log('Using cached function schema: %s/%d', funcName, numArgs);
+		return cached as FunctionSchema;
+	}
+
+	// Resolve function schema - try exact match first
+	let functionSchema = ctx.schemaManager.findFunction(funcName, numArgs);
+
+	// If not found, try variable argument function
+	if (!functionSchema) {
+		functionSchema = ctx.schemaManager.findFunction(funcName, -1);
+	}
+
+	if (!functionSchema) {
+		throw new QuereusError(
+			`Function not found: ${funcName}/${numArgs}`,
+			StatusCode.ERROR
+		);
+	}
+
+	// Record dependency using the actual function's numArgs
+	const dependency: SchemaDependency = {
+		type: 'function',
+		objectName: `${functionSchema.name}/${functionSchema.numArgs}`
+	};
+	ctx.schemaDependencies.recordDependency(dependency, functionSchema);
+
+	// Cache result with the requested key for future lookups
+	ctx.schemaCache.set(cacheKey, functionSchema);
+
+	log('Resolved function schema: %s/%d', functionSchema.name, functionSchema.numArgs);
+	return functionSchema;
+}
+
+/**
+ * Resolves a virtual table module at build time and records the dependency.
+ */
+export function resolveVtabModule(
+	ctx: PlanningContext,
+	moduleName: string
+): { module: VirtualTableModule<any, any>, auxData?: unknown } {
+	const cacheKey = `vtab_module:${moduleName}`;
+
+	// Check cache first
+	const cached = ctx.schemaCache.get(cacheKey);
+	if (cached) {
+		log('Using cached vtab module: %s', moduleName);
+		return cached;
+	}
+
+	// Resolve vtab module
+	const moduleInfo = ctx.schemaManager.getModule(moduleName);
+	if (!moduleInfo) {
+		throw new QuereusError(
+			`Virtual table module not found: ${moduleName}`,
+			StatusCode.ERROR
+		);
+	}
+
+	// Record dependency
+	const dependency: SchemaDependency = {
+		type: 'vtab_module',
+		objectName: moduleName
+	};
+	ctx.schemaDependencies.recordDependency(dependency, moduleInfo);
+
+	// Cache result
+	ctx.schemaCache.set(cacheKey, moduleInfo);
+
+	log('Resolved vtab module: %s', moduleName);
+	return moduleInfo;
+}
+
+/**
+ * Resolves a collation function at build time and records the dependency.
+ */
+export function resolveCollation(
+	ctx: PlanningContext,
+	collationName: string
+): CollationFunction {
+	const cacheKey = `collation:${collationName}`;
+
+	// Check cache first
+	const cached = ctx.schemaCache.get(cacheKey);
+	if (cached) {
+		log('Using cached collation: %s', collationName);
+		return cached as CollationFunction;
+	}
+
+	// Resolve collation
+	const collation = ctx.db._getCollation(collationName);
+	if (!collation) {
+		throw new QuereusError(
+			`Collation not found: ${collationName}`,
+			StatusCode.ERROR
+		);
+	}
+
+	// Record dependency
+	const dependency: SchemaDependency = {
+		type: 'collation',
+		objectName: collationName
+	};
+	ctx.schemaDependencies.recordDependency(dependency, collation);
+
+	// Cache result
+	ctx.schemaCache.set(cacheKey, collation);
+
+	log('Resolved collation: %s', collationName);
+	return collation;
+}

package/src/planner/building/select-aggregates.ts

@@ -0,0 +1,245 @@
+import type * as AST from '../../parser/ast.js';
+import type { RelationalPlanNode, ScalarPlanNode } from '../nodes/plan-node.js';
+import type { PlanningContext } from '../planning-context.js';
+import { AggregateNode } from '../nodes/aggregate-node.js';
+import { FilterNode } from '../nodes/filter.js';
+import { SortNode, type SortKey } from '../nodes/sort.js';
+import { type Projection } from '../nodes/project-node.js';
+import { RegisteredScope } from '../scopes/registered.js';
+import { ColumnReferenceNode } from '../nodes/reference.js';
+import { buildExpression } from './expression.js';
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+
+/**
+ * Processes GROUP BY, aggregates, and HAVING clauses
+ */
+export function buildAggregatePhase(
+	input: RelationalPlanNode,
+	stmt: AST.SelectStmt,
+	selectContext: PlanningContext,
+	aggregates: { expression: ScalarPlanNode; alias: string }[],
+	hasAggregates: boolean,
+	projections: Projection[]
+): {
+	output: RelationalPlanNode;
+	aggregateScope?: RegisteredScope;
+	needsFinalProjection: boolean;
+	preAggregateSort: boolean;
+} {
+	// If there is a HAVING clause but the SELECT contains **no aggregate functions**
+	// we can safely treat the HAVING predicate as a regular filter that runs *before*
+	// the aggregation (i.e. between the source and the AggregateNode). This avoids
+	// the "missing column context" problem where the predicate refers to columns
+	// that are not available after the AggregateNode (only grouping columns and
+	// aggregate results are exposed). This behaviour is compatible with SQLite –
+	// GROUP BY with a primary-key guarantees one row per group so the semantics
+	// are unchanged.
+	const shouldPushHavingBelowAggregate = Boolean(stmt.having && !hasAggregates);
+
+	const hasGroupBy = stmt.groupBy && stmt.groupBy.length > 0;
+
+	if (!hasAggregates && !hasGroupBy) {
+		return { output: input, needsFinalProjection: false, preAggregateSort: false };
+	}
+
+	// ---------------------------------------------------------------------------
+	// Build HAVING predicate as *pre-aggregate* filter when appropriate
+	// ---------------------------------------------------------------------------
+	let currentInput: RelationalPlanNode = input;
+	if (shouldPushHavingBelowAggregate) {
+		// Build the predicate using the *pre-aggregate* scope because all columns
+		// are still available here.
+		const havingExpr = buildExpression(selectContext, stmt.having as AST.Expression, true);
+		currentInput = new FilterNode(selectContext.scope, currentInput, havingExpr);
+	}
+
+	// After (optional) early HAVING filter we continue with the existing pipeline
+	// ----------------------------------------------------------------------------
+	// Handle pre-aggregate sorting for ORDER BY without GROUP BY
+	const preAggregateSort = Boolean(hasAggregates && !hasGroupBy && stmt.orderBy && stmt.orderBy.length > 0);
+	currentInput = handlePreAggregateSort(currentInput, stmt, selectContext, hasAggregates, !!hasGroupBy);
+
+	// Validate aggregate/non-aggregate mixing
+	validateAggregateProjections(projections, hasAggregates, !!hasGroupBy);
+
+	// Build GROUP BY expressions
+	const groupByExpressions = stmt.groupBy ?
+		stmt.groupBy.map(expr => buildExpression(selectContext, expr, false)) : [];
+
+	// Create AggregateNode
+	currentInput = new AggregateNode(selectContext.scope, currentInput, groupByExpressions, aggregates);
+
+	// Create aggregate output scope
+	const aggregateOutputScope = createAggregateOutputScope(
+		selectContext.scope,
+		currentInput,
+		groupByExpressions,
+		aggregates
+	);
+
+	// Handle HAVING clause *after* aggregation only when we did not already push
+	// it below the AggregateNode.
+	if (stmt.having && !shouldPushHavingBelowAggregate) {
+		currentInput = buildHavingFilter(currentInput, stmt.having, selectContext, aggregateOutputScope, aggregates, groupByExpressions);
+	}
+
+	// Determine if final projection is needed
+	const needsFinalProjection = checkNeedsFinalProjection(projections);
+
+	return {
+		output: currentInput,
+		aggregateScope: aggregateOutputScope,
+		needsFinalProjection,
+		preAggregateSort
+	};
+}
+
+/**
+ * Handles pre-aggregate sorting for special cases
+ */
+function handlePreAggregateSort(
+	input: RelationalPlanNode,
+	stmt: AST.SelectStmt,
+	selectContext: PlanningContext,
+	hasAggregates: boolean,
+	hasGroupBy: boolean
+): RelationalPlanNode {
+	// Special handling for ORDER BY with aggregates but no GROUP BY
+	if (hasAggregates && !hasGroupBy && stmt.orderBy && stmt.orderBy.length > 0) {
+		// Apply ORDER BY before aggregation
+		const sortKeys: SortKey[] = stmt.orderBy.map(orderByClause => {
+			const expression = buildExpression(selectContext, orderByClause.expr);
+			return {
+				expression,
+				direction: orderByClause.direction,
+				nulls: orderByClause.nulls
+			};
+		});
+
+		return new SortNode(selectContext.scope, input, sortKeys);
+	}
+
+	return input;
+}
+
+/**
+ * Validates that aggregate and non-aggregate projections don't mix inappropriately
+ */
+function validateAggregateProjections(
+	projections: Projection[],
+	hasAggregates: boolean,
+	hasGroupBy: boolean
+): void {
+	if (projections.length > 0 && hasAggregates && !hasGroupBy) {
+		throw new QuereusError(
+			'Cannot mix aggregate and non-aggregate columns in SELECT list without GROUP BY',
+			StatusCode.ERROR
+		);
+	}
+}
+
+/**
+ * Creates a scope that includes the aggregate output columns
+ */
+function createAggregateOutputScope(
+	parentScope: any,
+	aggregateNode: RelationalPlanNode,
+	groupByExpressions: ScalarPlanNode[],
+	aggregates: { expression: ScalarPlanNode; alias: string }[]
+): RegisteredScope {
+	const aggregateOutputScope = new RegisteredScope(parentScope);
+	const aggregateAttributes = aggregateNode.getAttributes();
+
+	// Register GROUP BY columns
+	groupByExpressions.forEach((expr, index) => {
+		const attr = aggregateAttributes[index];
+		aggregateOutputScope.registerSymbol(attr.name.toLowerCase(), (exp, s) =>
+			new ColumnReferenceNode(s, exp as AST.ColumnExpr, expr.getType(), attr.id, index));
+	});
+
+	// Register aggregate columns by their aliases
+	aggregates.forEach((agg, index) => {
+		const columnIndex = groupByExpressions.length + index;
+		const attr = aggregateAttributes[columnIndex];
+		aggregateOutputScope.registerSymbol(agg.alias.toLowerCase(), (exp, s) =>
+			new ColumnReferenceNode(s, exp as AST.ColumnExpr, agg.expression.getType(), attr.id, columnIndex));
+	});
+
+	return aggregateOutputScope;
+}
+
+/**
+ * Builds HAVING filter clause
+ */
+function buildHavingFilter(
+	input: RelationalPlanNode,
+	havingClause: AST.Expression,
+	selectContext: PlanningContext,
+	aggregateOutputScope: RegisteredScope,
+	aggregates: { expression: ScalarPlanNode; alias: string }[],
+	groupByExpressions: ScalarPlanNode[]
+): RelationalPlanNode {
+	const aggregateAttributes = input.getAttributes();
+
+	// Build HAVING expression with the aggregate scope
+	const havingContext: PlanningContext = {
+		...selectContext,
+		scope: aggregateOutputScope,
+		aggregates: aggregates.map((agg, index) => {
+			const columnIndex = groupByExpressions.length + index;
+			const attr = aggregateAttributes[columnIndex];
+			return {
+				expression: agg.expression,
+				alias: agg.alias,
+				columnIndex,
+				attributeId: attr.id
+			};
+		})
+	};
+
+	const havingExpression = buildExpression(havingContext, havingClause, true);
+
+	return new FilterNode(aggregateOutputScope, input, havingExpression);
+}
+
+/**
+ * Checks if a final projection is needed for complex expressions
+ */
+function checkNeedsFinalProjection(projections: Projection[]): boolean {
+	if (projections.length === 0) {
+		return false;
+	}
+
+	// Check if any of the projections are complex expressions (not just column refs)
+	return projections.some(proj => {
+		// If it's not a simple ColumnReferenceNode, we need final projection
+		return !(proj.node instanceof ColumnReferenceNode);
+	});
+}
+
+/**
+ * Builds final projections for the complete SELECT list in aggregate context
+ */
+export function buildFinalAggregateProjections(
+	stmt: AST.SelectStmt,
+	selectContext: PlanningContext,
+	aggregateOutputScope: RegisteredScope
+): Projection[] {
+	const finalProjections: Projection[] = [];
+
+	for (const column of stmt.columns) {
+		if (column.type === 'column') {
+			// Re-build the expression in the context of the aggregate output
+			const finalContext: PlanningContext = { ...selectContext, scope: aggregateOutputScope };
+			const scalarNode = buildExpression(finalContext, column.expr, true);
+
+			finalProjections.push({
+				node: scalarNode,
+				alias: column.alias || (column.expr.type === 'column' ? column.expr.name : undefined)
+			});
+		}
+	}
+
+	return finalProjections;
+}

package/src/planner/building/select-compound.ts

@@ -0,0 +1,110 @@
+import type * as AST from '../../parser/ast.js';
+import type { RelationalPlanNode } from '../nodes/plan-node.js';
+import type { PlanningContext } from '../planning-context.js';
+import type { CTEPlanNode } from '../nodes/cte-node.js';
+import { SetOperationNode } from '../nodes/set-operation-node.js';
+import { SortNode, type SortKey } from '../nodes/sort.js';
+import { LimitOffsetNode } from '../nodes/limit-offset.js';
+import { LiteralNode } from '../nodes/scalar.js';
+import { RegisteredScope } from '../scopes/registered.js';
+import { ColumnReferenceNode } from '../nodes/reference.js';
+import { buildExpression } from './expression.js';
+// Import will be added after refactoring select.ts
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+
+/**
+ * Builds a compound SELECT statement (UNION, INTERSECT, EXCEPT)
+ */
+export function buildCompoundSelect(
+	stmt: AST.SelectStmt,
+	contextWithCTEs: PlanningContext,
+	cteNodes: Map<string, CTEPlanNode>,
+	buildSelectStmt: (ctx: PlanningContext, stmt: AST.SelectStmt, parentCTEs?: Map<string, CTEPlanNode>) => RelationalPlanNode
+): RelationalPlanNode {
+	if (!stmt.compound) {
+		throw new QuereusError('buildCompoundSelect called without compound clause', StatusCode.INTERNAL);
+	}
+
+	// Build left side by cloning the statement without compound and stripping ORDER BY/LIMIT/OFFSET that belong to outer query
+	const { compound: _outerCompound, orderBy: outerOrderBy, limit: outerLimit, offset: outerOffset, ...leftCore } = stmt as any;
+
+	// Also strip ORDER BY/LIMIT/OFFSET from the right side - they should only apply to the final compound result
+	const { orderBy: _rightOrderBy, limit: _rightLimit, offset: _rightOffset, ...rightCore } = stmt.compound.select as any;
+
+	const leftPlan = buildSelectStmt(contextWithCTEs, leftCore as AST.SelectStmt, cteNodes) as RelationalPlanNode;
+	const rightPlan = buildSelectStmt(contextWithCTEs, rightCore as AST.SelectStmt, cteNodes) as RelationalPlanNode;
+
+	const setNode = new SetOperationNode(contextWithCTEs.scope, leftPlan, rightPlan, stmt.compound.op);
+
+	// After set operation, apply ORDER BY / LIMIT / OFFSET from the *outer* (original) statement
+	let input: RelationalPlanNode = setNode;
+
+	// Build scope for output columns
+	const setScope = createSetOperationScope(input);
+	const selectContext: PlanningContext = { ...contextWithCTEs, scope: setScope };
+
+	// Apply outer modifiers
+	input = applyOuterOrderBy(input, outerOrderBy, selectContext);
+	input = applyOuterLimitOffset(input, outerLimit, outerOffset, selectContext);
+
+	return input;
+}
+
+/**
+ * Creates a scope for set operation output columns
+ */
+function createSetOperationScope(setNode: RelationalPlanNode): RegisteredScope {
+	const setScope = new RegisteredScope();
+	const attrs = setNode.getAttributes();
+
+	setNode.getType().columns.forEach((c: any, i: number) => {
+		const attr = attrs[i];
+		// Ensure column has a name - use attribute name as fallback
+		const columnName = c.name || attr.name;
+		if (!columnName) {
+			throw new QuereusError(`Column at index ${i} has no name in set operation`, StatusCode.ERROR);
+		}
+		setScope.registerSymbol(columnName.toLowerCase(), (exp: any, s: any) =>
+			new ColumnReferenceNode(s, exp, c.type, attr.id, i));
+	});
+
+	return setScope;
+}
+
+/**
+ * Applies ORDER BY clause from outer compound statement
+ */
+function applyOuterOrderBy(
+	input: RelationalPlanNode,
+	outerOrderBy: any[] | undefined,
+	selectContext: PlanningContext
+): RelationalPlanNode {
+	if (outerOrderBy && outerOrderBy.length > 0) {
+		const sortKeys: SortKey[] = outerOrderBy.map((ob: any) => ({
+			expression: buildExpression(selectContext, ob.expr),
+			direction: ob.direction,
+			nulls: ob.nulls,
+		}));
+		return new SortNode(selectContext.scope, input, sortKeys);
+	}
+	return input;
+}
+
+/**
+ * Applies LIMIT and OFFSET clauses from outer compound statement
+ */
+function applyOuterLimitOffset(
+	input: RelationalPlanNode,
+	outerLimit: any,
+	outerOffset: any,
+	selectContext: PlanningContext
+): RelationalPlanNode {
+	if (outerLimit || outerOffset) {
+		const literalNull = new LiteralNode(selectContext.scope, { type: 'literal', value: null });
+		const limitExpr = outerLimit ? buildExpression(selectContext, outerLimit) : literalNull;
+		const offsetExpr = outerOffset ? buildExpression(selectContext, outerOffset) : literalNull;
+		return new LimitOffsetNode(selectContext.scope, input, limitExpr, offsetExpr);
+	}
+	return input;
+}

package/src/planner/building/select-context.ts

@@ -0,0 +1,75 @@
+import type * as AST from '../../parser/ast.js';
+import type { PlanningContext } from '../planning-context.js';
+import type { CTEPlanNode } from '../nodes/cte-node.js';
+import type { Scope } from '../scopes/scope.js';
+import { RegisteredScope } from '../scopes/registered.js';
+import { ParameterScope } from '../scopes/param.js';
+import { ColumnReferenceNode } from '../nodes/reference.js';
+import { buildWithClause } from './with.js';
+
+/**
+ * Helper function to get the non-parameter ancestor scope.
+ * This ensures table/column scopes don't inherit from ParameterScope,
+ * preventing parameter resolution ambiguity in MultiScope.
+ */
+export function getNonParamAncestor(scope: Scope): Scope {
+	return (scope instanceof ParameterScope) ? scope.parentScope : scope;
+}
+
+/**
+ * Builds context with CTEs if present
+ */
+export function buildWithContext(
+	ctx: PlanningContext,
+	stmt: AST.SelectStmt,
+	parentCTEs: Map<string, CTEPlanNode> = new Map()
+): {
+	contextWithCTEs: PlanningContext;
+	cteNodes: Map<string, CTEPlanNode>;
+} {
+	// Start with parent CTEs
+	const cteNodes: Map<string, CTEPlanNode> = new Map(parentCTEs);
+	let contextWithCTEs = ctx;
+
+	if (stmt.withClause) {
+		const newCteNodes = buildWithClause(ctx, stmt.withClause);
+		// Merge parent CTEs with new ones (new ones take precedence)
+		for (const [name, node] of newCteNodes) {
+			cteNodes.set(name, node);
+		}
+
+		// Create a new scope that includes the CTEs
+		const cteScope = createCTEScope(cteNodes, ctx);
+		contextWithCTEs = { ...ctx, scope: cteScope };
+	} else if (parentCTEs.size > 0) {
+		// No WITH clause but we have parent CTEs, create scope for them
+		const cteScope = createCTEScope(parentCTEs, ctx);
+		contextWithCTEs = { ...ctx, scope: cteScope };
+	}
+
+	return { contextWithCTEs, cteNodes };
+}
+
+/**
+ * Creates a scope that includes CTE references
+ */
+function createCTEScope(
+	cteNodes: Map<string, CTEPlanNode>,
+	ctx: PlanningContext
+): RegisteredScope {
+	const cteScope = new RegisteredScope(getNonParamAncestor(ctx.scope));
+
+	// Register each CTE in the scope
+	for (const [cteName, cteNode] of cteNodes) {
+		const attributes = cteNode.getAttributes();
+		cteNode.getType().columns.forEach((col: any, i: number) => {
+			const attr = attributes[i];
+			// Register CTE columns with qualified names to avoid collisions
+			const qualifiedColumnName = `${cteName}.${col.name.toLowerCase()}`;
+			cteScope.registerSymbol(qualifiedColumnName, (exp, s) =>
+				new ColumnReferenceNode(s, exp as AST.ColumnExpr, col.type, attr.id, i));
+		});
+	}
+
+	return cteScope;
+}