Improve readability and docs

Author: JanJakes

tests/WP_SQLite_Driver_Translation_Tests.php

@@ -1380,6 +1380,12 @@ public function testSelectOrderByAmbiguousColumnResolution(): void {
 			'SELECT t1.name AS t1_name FROM t1 JOIN t2 ON t2.id = t1.id ORDER BY name DESC'
 		);
 
+		// When the SELECT item list is ambiguous, the ORDER BY column is not disambiguated (like in MySQL).
+		$this->assertQuery(
+			'SELECT `t1`.`name` , `t2`.`name` FROM `t1` JOIN `t2` ON `t2`.`id` = `t1`.`id` ORDER BY `name` DESC',
+			'SELECT t1.name, t2.name FROM t1 JOIN t2 ON t2.id = t1.id ORDER BY name DESC'
+		);
+
 		// When the ORDER BY item uses an alias, there is no ambiguity.
 		$this->assertQuery(
 			'SELECT `t1`.`name` AS `t1_name` FROM `t1` JOIN `t2` ON `t2`.`t1_id` = `t1`.`id` ORDER BY `t1_name` DESC',

wp-includes/sqlite-ast/class-wp-sqlite-driver.php

@@ -2949,44 +2949,73 @@ private function translate_query_expression( WP_Parser_Node $node ): string {
 			// Get a list of column references used in the SELECT item list.
 			$select_column_refs = array();
 			foreach ( $select_item_list->get_child_nodes() as $select_item ) {
-				// When the SELECT item uses an alias, the column is not disambiguated.
+				/*
+				 * [GRAMMAR]
+				 * selectItem: tableWild | (expr selectAlias?)
+				 */
+
+				// Skip when a "tableWild" node is used (no "expr" node).
+				$select_item_expr = $select_item->get_first_child_node( 'expr' );
+				if ( ! $select_item_expr ) {
+					continue;
+				}
+
+				// Skip when a SELECT item alias is used (as per MySQL behavior).
 				if ( $select_item->has_child_node( 'selectAlias' ) ) {
 					continue;
 				}
 
-				$select_item_expr = $select_item->get_first_child_node( 'expr' );
-				if ( ! $select_item_expr ) {
+				// Skip when there is no column listed (no "columnRef" node).
+				$select_column_ref = $select_item_expr->get_first_descendant_node( 'columnRef' );
+				if ( ! $select_column_ref ) {
 					continue;
 				}
 
-				$select_item_expr  = $this->unnest_parenthesized_expression( $select_item_expr );
-				$select_column_ref = $select_item->get_first_descendant_node( 'columnRef' );
-				if (
-					$select_column_ref
-					&& $this->translate( $select_item_expr ) === $this->translate( $select_column_ref )
-				) {
+				// Support also parenthesized column references (e.g. "(t.id)").
+				$select_item_expr = $this->unnest_parenthesized_expression( $select_item_expr );
+
+				// Consider only simple and parenthesized column references.
+				$expr_value   = $this->translate( $select_item_expr );
+				$column_value = $this->translate( $select_column_ref );
+				if ( $expr_value === $column_value ) {
 					$select_column_refs[] = $select_column_ref;
 				}
 			}
 
 			// For each ORDER BY item, try to find a corresponding SELECT item.
 			foreach ( $order_list->get_child_nodes() as $order_item ) {
+				/*
+				 * [GRAMMAR]
+				 * orderExpression: expr direction?
+				 */
 				$order_expr       = $order_item->get_first_child_node( 'expr' );
 				$order_column_ref = $order_expr->get_first_descendant_node( 'columnRef' );
 
-				$select_item_matches = array();
+				// Skip when there is no column in the ORDER BY item (no "columnRef"
+				// node), or when the item is qualified (has a "dotIdentifier" node).
 				if (
-					$order_column_ref
-					&& $this->translate( $order_column_ref ) === $this->translate( $order_expr )
-					&& null === $order_column_ref->get_first_descendant_node( 'dotIdentifier' )
+					! $order_column_ref
+					|| null !== $order_column_ref->get_first_descendant_node( 'dotIdentifier' )
 				) {
-					// Look for select items that match the column reference.
+					$disambiguated_order_list[] = $this->translate( $order_item );
+					continue;
+				}
+
+				// Consider only simple and parenthesized column references.
+				$order_expr_value   = $this->translate( $order_expr );
+				$order_column_value = $this->translate( $order_column_ref );
+
+				// Look for select items that match the column reference.
+				$select_item_matches = array();
+				if ( $order_expr_value === $order_column_value ) {
 					foreach ( $select_column_refs as $select_column_ref ) {
+						// Skip non-qualified column references in the SELECT item.
 						$dot_identifiers = $select_column_ref->get_descendant_nodes( 'dotIdentifier' );
 						if ( count( $dot_identifiers ) === 0 ) {
 							continue;
 						}
 
+						// Compare only the column names (last "dotIdentifier" node).
 						$last_dot_identifier = end( $dot_identifiers );
 						$select_column_name  = $this->translate( $last_dot_identifier->get_first_child_node() );
 						$order_column_name   = $this->translate( $order_column_ref );
@@ -2996,6 +3025,8 @@ private function translate_query_expression( WP_Parser_Node $node ): string {
 					}
 				}
 
+				// When we find exactly one SELECT item, we can disambiguate the
+				// reference. Otherwise, fall back to the original ORDER BY item.
 				if ( 1 === count( $select_item_matches ) ) {
 					$direction             = $order_item->get_first_child_node( 'direction' );
 					$translated_order_item = sprintf(