@quereus/quereus 0.7.3 → 0.7.5

package/src/planner/framework/context.ts

@@ -1,239 +0,0 @@
-/**
- * Optimizer context that wraps Optimizer with StatsProvider and other utilities
- * Provides unified interface for optimization rules
- */
-
-import type { Optimizer } from '../optimizer.js';
-import type { StatsProvider } from '../stats/index.js';
-import type { OptimizerTuning } from '../optimizer-tuning.js';
-import { createLogger } from '../../common/logger.js';
-import { StatusCode } from '../../common/types.js';
-import { quereusError } from '../../common/errors.js';
-import { Database } from '../../core/database.js';
-import type { PlanNode } from '../nodes/plan-node.js';
-
-const log = createLogger('optimizer:framework:context');
-
-/**
- * Context object passed to optimization rules
- * Contains all the utilities and data sources rules need
- */
-export interface OptContext {
-	/** The optimizer instance */
-	readonly optimizer: Optimizer;
-
-	/** Statistics provider for cardinality and selectivity estimates */
-	readonly stats: StatsProvider;
-
-	/** Optimizer tuning parameters */
-	readonly tuning: OptimizerTuning;
-
-	/** Current optimization phase */
-	readonly phase: 'rewrite' | 'impl';
-
-	/** Rule application depth (for detecting infinite recursion) */
-	readonly depth: number;
-
-	/** Additional context data that rules can use */
-	readonly context: Map<string, unknown>;
-
-	/** Diagnostics bag that rules can populate (emitted after optimization) */
-	readonly diagnostics: OptimizerDiagnostics;
-
-	/** Database instance */
-	readonly db: Database;
-
-	/** Context-scoped visited rules tracking (nodeId → ruleIds) */
-	readonly visitedRules: Map<string, Set<string>>;
-
-	/** Cache of already-optimized nodes within this context (nodeId → optimized result) */
-	readonly optimizedNodes: Map<string, PlanNode>;
-}
-
-/** Optimizer diagnostics structure */
-export interface OptimizerDiagnostics {
-  // QuickPick join enumeration
-  quickpick?: {
-    tours?: number;
-    bestCost?: number;
-  };
-  // Extensible for future diagnostics
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  [key: string]: any;
-}
-
-/**
- * Implementation of optimization context
- */
-export class OptimizationContext implements OptContext {
-	readonly context = new Map<string, unknown>();
-	readonly visitedRules = new Map<string, Set<string>>();
-	readonly optimizedNodes = new Map<string, PlanNode>();
-  readonly diagnostics = {} as OptimizerDiagnostics;
-
-	constructor(
-		public readonly optimizer: Optimizer,
-		public readonly stats: StatsProvider,
-		public readonly tuning: OptimizerTuning,
-		public readonly phase: 'rewrite' | 'impl' = 'rewrite',
-		public readonly db: Database,
-		public readonly depth: number = 0,
-	) {
-		log('Created optimization context (phase: %s, depth: %d)', phase, depth);
-	}
-
-	/**
-	 * Create a new context for a different phase
-	 */
-	withPhase(phase: 'rewrite' | 'impl'): OptimizationContext {
-		const newContext = new OptimizationContext(
-			this.optimizer,
-			this.stats,
-			this.tuning,
-			phase,
-			this.db,
-			this.depth,
-		);
-
-		// Copy visited tracking state
-		this.copyTrackingState(newContext);
-		return newContext;
-	}
-
-	/**
-	 * Create a new context with incremented depth
-	 */
-	withIncrementedDepth(): OptimizationContext {
-		if (this.depth >= this.tuning.maxOptimizationDepth) {
-			quereusError(`Maximum optimization depth exceeded: ${this.depth}`, StatusCode.ERROR);
-		}
-
-		const newContext = new OptimizationContext(
-			this.optimizer,
-			this.stats,
-			this.tuning,
-			this.phase,
-			this.db,
-			this.depth + 1,
-		);
-
-		// Copy visited tracking state
-		this.copyTrackingState(newContext);
-		return newContext;
-	}
-
-	/**
-	 * Create a new context with additional context data
-	 */
-	withContext(key: string, value: unknown): OptimizationContext {
-		const newContext = new OptimizationContext(
-			this.optimizer,
-			this.stats,
-			this.tuning,
-			this.phase,
-			this.db,
-			this.depth,
-		);
-
-		// Copy existing context
-		for (const [k, v] of this.context) {
-			newContext.context.set(k, v);
-		}
-
-		// Add new context
-		newContext.context.set(key, value);
-
-		// Copy visited tracking state
-		this.copyTrackingState(newContext);
-		return newContext;
-	}
-
-	/**
-	 * Copy visited tracking state to another context
-	 */
-	private copyTrackingState(target: OptimizationContext): void {
-		// Copy visitedRules
-		for (const [nodeId, ruleIds] of this.visitedRules) {
-			target.visitedRules.set(nodeId, new Set(ruleIds));
-		}
-
-		// Copy optimizedNodes
-		for (const [nodeId, node] of this.optimizedNodes) {
-			target.optimizedNodes.set(nodeId, node);
-		}
-	}
-
-	/**
-	 * Get context value
-	 */
-	getContext<T>(key: string): T | undefined {
-		return this.context.get(key) as T | undefined;
-	}
-
-	/**
-	 * Check if context has a key
-	 */
-	hasContext(key: string): boolean {
-		return this.context.has(key);
-	}
-
-	/**
-	 * Set context value (mutates current context)
-	 */
-	setContext(key: string, value: unknown): void {
-		this.context.set(key, value);
-	}
-
-	/**
-	 * Remove context value (mutates current context)
-	 */
-	deleteContext(key: string): boolean {
-		return this.context.delete(key);
-	}
-
-	/**
-	 * Clear all context data (mutates current context)
-	 */
-	clearContext(): void {
-		this.context.clear();
-	}
-
-	/**
-	 * Get a snapshot of all context data
-	 */
-	getContextSnapshot(): Record<string, unknown> {
-		const snapshot: Record<string, unknown> = {};
-		for (const [key, value] of this.context) {
-			snapshot[key] = value;
-		}
-		return snapshot;
-	}
-}
-
-/**
- * Factory function to create optimization context
- */
-export function createOptContext(
-	optimizer: Optimizer,
-	stats: StatsProvider,
-	tuning: OptimizerTuning,
-	db: Database,
-	phase: 'rewrite' | 'impl' = 'rewrite',
-): OptContext {
-	return new OptimizationContext(optimizer, stats, tuning, phase, db);
-}
-
-/**
- * Type guard to check if an object is an OptContext
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function isOptContext(obj: any): obj is OptContext {
-	return obj &&
-		typeof obj === 'object' &&
-		'optimizer' in obj &&
-		'stats' in obj &&
-		'tuning' in obj &&
-		'phase' in obj &&
-		'depth' in obj &&
-		'context' in obj;
-}

package/src/planner/framework/pass.ts

@@ -1,354 +0,0 @@
-/**
- * Optimization pass framework for multi-pass query optimization
- *
- * This framework enables rules to run in separate tree traversals,
- * allowing for proper sequencing of transformations that require
- * different traversal orders or multiple passes over the tree.
- */
-
-import type { PlanNode } from '../nodes/plan-node.js';
-import type { OptContext } from './context.js';
-import type { RuleHandle } from './registry.js';
-import { createLogger } from '../../common/logger.js';
-import { performConstantFolding } from '../analysis/const-pass.js';
-import { createRuntimeExpressionEvaluator } from '../analysis/const-evaluator.js';
-
-const log = createLogger('optimizer:framework:pass');
-
-/**
- * Traversal order for optimization passes
- */
-export enum TraversalOrder {
-	/** Process children before parents */
-	BottomUp = 'bottom-up',
-	/** Process parents before children */
-	TopDown = 'top-down',
-}
-
-/**
- * Definition of an optimization pass
- */
-export interface OptimizationPass {
-	/** Unique identifier for this pass */
-	id: string;
-
-	/** Human-readable name for logging */
-	name: string;
-
-	/** Description of what this pass does */
-	description: string;
-
-	/** Traversal order for this pass */
-	traversalOrder: TraversalOrder;
-
-	/** Rules that belong to this pass (will be populated by registration) */
-	rules: RuleHandle[];
-
-	/** Optional custom execution logic (default uses standard rule application) */
-	execute?: (plan: PlanNode, context: OptContext) => PlanNode;
-
-	/** Whether this pass is enabled (default: true) */
-	enabled?: boolean;
-
-	/** Order in which passes execute (lower numbers first) */
-	order: number;
-}
-
-/**
- * Standard optimization passes
- */
-export enum PassId {
-	/** Pre-optimization constant folding */
-	ConstantFolding = 'constant-folding',
-
-	/** Structural transformations (pushdown, pullup, boundary sliding) */
-	Structural = 'structural',
-
-	/** Physical operator selection and implementation */
-	Physical = 'physical',
-
-	/** Post-optimization cleanup and caching */
-	PostOptimization = 'post-opt',
-
-	/** Final validation */
-	Validation = 'validation',
-}
-
-/**
- * Create a standard optimization pass
- */
-export function createPass(
-	id: string,
-	name: string,
-	description: string,
-	order: number,
-	traversalOrder: TraversalOrder = TraversalOrder.BottomUp
-): OptimizationPass {
-	return {
-		id,
-		name,
-		description,
-		traversalOrder,
-		rules: [],
-		enabled: true,
-		order
-	};
-}
-
-/**
- * Create constant folding pass with custom execution
- */
-function createConstantFoldingPass(): OptimizationPass {
-	return {
-		id: PassId.ConstantFolding,
-		name: 'Constant Folding',
-		description: 'Pre-evaluate constant expressions and fold them into the plan',
-		traversalOrder: TraversalOrder.BottomUp,
-		rules: [],
-		enabled: true,
-		order: 0,
-		execute: (plan: PlanNode, context: OptContext) => {
-			// Custom execution for constant folding
-			const evaluator = createRuntimeExpressionEvaluator(context.db);
-			const result = performConstantFolding(plan, evaluator);
-			log('Constant folding completed');
-			return result;
-		}
-	};
-}
-
-/**
- * Standard pass definitions
- */
-export const STANDARD_PASSES: OptimizationPass[] = [
-	createConstantFoldingPass(),
-
-	createPass(
-		PassId.Structural,
-		'Structural Transformations',
-		'Restructure the plan tree for optimal execution boundaries',
-		10,
-		TraversalOrder.TopDown
-	),
-
-	createPass(
-		PassId.Physical,
-		'Physical Selection',
-		'Convert logical operators to physical implementations',
-		20,
-		TraversalOrder.BottomUp
-	),
-
-	createPass(
-		PassId.PostOptimization,
-		'Post-Optimization',
-		'Final cleanup, materialization decisions, and caching',
-		30,
-		TraversalOrder.BottomUp
-	),
-
-	createPass(
-		PassId.Validation,
-		'Validation',
-		'Validate the correctness of the optimized plan',
-		40,
-		TraversalOrder.BottomUp
-	),
-];
-
-/**
- * Pass manager for coordinating multi-pass optimization
- */
-export class PassManager {
-	private passes: Map<string, OptimizationPass> = new Map();
-	private sortedPasses: OptimizationPass[] = [];
-
-	constructor() {
-		// Register standard passes
-		for (const pass of STANDARD_PASSES) {
-			this.registerPass(pass);
-		}
-	}
-
-	/**
-	 * Register an optimization pass
-	 */
-	registerPass(pass: OptimizationPass): void {
-		if (this.passes.has(pass.id)) {
-			log('Warning: Overwriting existing pass %s', pass.id);
-		}
-
-		this.passes.set(pass.id, pass);
-		this.updateSortedPasses();
-
-		log('Registered pass %s (order: %d, traversal: %s)',
-			pass.id, pass.order, pass.traversalOrder);
-	}
-
-	/**
-	 * Get a pass by ID
-	 */
-	getPass(id: string): OptimizationPass | undefined {
-		return this.passes.get(id);
-	}
-
-	/**
-	 * Add a rule to a specific pass
-	 */
-	addRuleToPass(passId: string, rule: RuleHandle): void {
-		const pass = this.passes.get(passId);
-		if (!pass) {
-			throw new Error(`Unknown pass: ${passId}`);
-		}
-
-		// Avoid duplicate registrations by rule ID within a pass
-		if (pass.rules.some(r => r.id === rule.id)) {
-			log('Skipping duplicate rule %s for pass %s', rule.id, passId);
-			return;
-		}
-
-		pass.rules.push(rule);
-		log('Added rule %s to pass %s', rule.id, passId);
-	}
-
-	/**
-	 * Get all passes in execution order
-	 */
-	getPasses(): readonly OptimizationPass[] {
-		return this.sortedPasses;
-	}
-
-	/**
-	 * Update sorted pass list after changes
-	 */
-	private updateSortedPasses(): void {
-		this.sortedPasses = Array.from(this.passes.values())
-			.filter(pass => pass.enabled !== false)
-			.sort((a, b) => a.order - b.order);
-	}
-
-	/**
-	 * Execute all passes on a plan
-	 */
-	execute(plan: PlanNode, context: OptContext): PlanNode {
-		return this.executeUpTo(plan, context);
-	}
-
-	/**
-	 * Execute passes up to and including the specified pass id
-	 */
-	executeUpTo(plan: PlanNode, context: OptContext, upToPassId?: string): PlanNode {
-		let currentPlan = plan;
-		for (const pass of this.sortedPasses) {
-			log('Starting pass: %s', pass.name);
-
-			if (pass.execute) {
-				// Custom execution logic
-				currentPlan = pass.execute(currentPlan, context);
-			} else {
-				// Standard rule-based execution
-				currentPlan = this.executeStandardPass(currentPlan, context, pass);
-			}
-
-			log('Completed pass: %s', pass.name);
-			if (upToPassId && pass.id === upToPassId) break;
-		}
-		return currentPlan;
-	}
-
-	/**
-	 * Execute a standard rule-based pass
-	 */
-	private executeStandardPass(
-		plan: PlanNode,
-		context: OptContext,
-		pass: OptimizationPass
-	): PlanNode {
-		// This will be implemented to traverse the tree in the specified order
-		// and apply the pass's rules at each node
-
-		if (pass.traversalOrder === TraversalOrder.TopDown) {
-			return this.traverseTopDown(plan, context, pass);
-		} else {
-			return this.traverseBottomUp(plan, context, pass);
-		}
-	}
-
-	/**
-	 * Top-down traversal with rule application
-	 */
-	private traverseTopDown(
-		node: PlanNode,
-		context: OptContext,
-		pass: OptimizationPass
-	): PlanNode {
-		// Apply rules to this node first
-		let currentNode = this.applyPassRules(node, context, pass);
-
-		// Then traverse children
-		const children = currentNode.getChildren();
-		if (children.length > 0) {
-			const newChildren = children.map(child =>
-				this.traverseTopDown(child, context, pass)
-			);
-
-			// Only create new node if children changed
-			const childrenChanged = children.some((child, i) => child !== newChildren[i]);
-			if (childrenChanged) {
-				currentNode = currentNode.withChildren(newChildren);
-			}
-		}
-
-		return currentNode;
-	}
-
-	/**
-	 * Bottom-up traversal with rule application
-	 */
-	private traverseBottomUp(
-		node: PlanNode,
-		context: OptContext,
-		pass: OptimizationPass
-	): PlanNode {
-		// Traverse children first
-		const children = node.getChildren();
-		let currentNode = node;
-
-		if (children.length > 0) {
-			const newChildren = children.map(child =>
-				this.traverseBottomUp(child, context, pass)
-			);
-
-			// Only create new node if children changed
-			const childrenChanged = children.some((child, i) => child !== newChildren[i]);
-			if (childrenChanged) {
-				currentNode = currentNode.withChildren(newChildren);
-			}
-		}
-
-		// Then apply rules to this node
-		return this.applyPassRules(currentNode, context, pass);
-	}
-
-	/**
-	 * Apply all rules in a pass to a node
-	 */
-	private applyPassRules(
-		node: PlanNode,
-		context: OptContext,
-		pass: OptimizationPass
-	): PlanNode {
-		let currentNode = node;
-		// Apply rules against the current node type only
-		for (const rule of pass.rules) {
-			if (rule.nodeType !== currentNode.nodeType) continue;
-			const result = rule.fn(currentNode, context);
-			if (result && result !== currentNode) {
-				log('Rule %s transformed node in pass %s', rule.id, pass.id);
-				currentNode = result;
-			}
-		}
-
-		return currentNode;
-	}
-}