fix(grid): resolve column comments through source metadata

Closes #6054

apps/desktop/src/components/grid/DataGrid.vue

@@ -561,9 +561,13 @@ const infiniteScrollMaxRows = computed(() => continuousQueryResultMaxRows(settin
 const flatteningMultiLineEnabled = computed(() => settingsStore.editorSettings.flatteningMultiLineText);
 const expandedCellEditor = ref<{ rowId: number; col: number } | null>(null);
 
-function headerColumnComment(column: string): string {
+function resolvedColumnComment(column: string, actualColIdx: number): string | undefined {
+  return dataGridColumnCommentFor(columnCommentMap.value, column, props.sourceColumns?.[actualColIdx]);
+}
+
+function headerColumnComment(column: string, actualColIdx: number): string {
   if (!showColumnCommentsInHeader.value) return "";
-  return columnCommentMap.value.get(column) || "";
+  return resolvedColumnComment(column, actualColIdx) ?? "";
 }
 
 function headerColumnType(column: string, actualColIdx: number): string {
@@ -582,7 +586,7 @@ function headerColumnNullability(actualColIdx: number): "nullable" | "required"
 
 const reserveColumnTypeLine = computed(() => reserveDataGridHeaderLine(showColumnTypesInHeader.value, props.result.columns, (column, index) => headerColumnType(column, index)));
 // Match the rendered header columns so comments from unprojected metadata cannot add an empty row.
-const reserveColumnCommentLine = computed(() => reserveDataGridHeaderLine(showColumnCommentsInHeader.value, props.result.columns, (column) => headerColumnComment(column)));
+const reserveColumnCommentLine = computed(() => reserveDataGridHeaderLine(showColumnCommentsInHeader.value, props.result.columns, (column, index) => headerColumnComment(column, index)));
 
 function shortTypeName(t: string): string {
   const s = t.toLowerCase();
@@ -10366,11 +10370,11 @@ const gridContextMenuItems = computed<ContextMenuItem[]>(() => {
                     :frozen-separator="frozenColumnCount > 0 && col.visibleColIdx === frozenColumnCount - 1"
                     :tooltip-disabled="columnHeaderTooltipsDisabled"
                     :column-type="headerColumnType(col.name, col.actualColIdx)"
-                    :column-comment="headerColumnComment(col.name)"
+                    :column-comment="headerColumnComment(col.name, col.actualColIdx)"
                     :show-type-line="reserveColumnTypeLine"
                     :show-comment-line="reserveColumnCommentLine"
                     :tooltip-column-type="columnTypeMap.get(col.name)"
-                    :tooltip-column-comment="columnCommentMap.get(col.name)"
+                    :tooltip-column-comment="resolvedColumnComment(col.name, col.actualColIdx)"
                     :column-nullability="headerColumnNullability(col.actualColIdx)"
                     :type-class="typeColorClass(headerColumnType(col.name, col.actualColIdx))"
                     :drag-class="columnHeaderDragClass(col.visibleColIdx)"

apps/desktop/src/components/grid/__tests__/DataGridColumnComments.spec.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const dataGridSource = readFileSync(new URL("../DataGrid.vue", import.meta.url), "utf8");
+
+describe("DataGrid column comments", () => {
+  it("uses source column metadata for both inline and tooltip header comments", () => {
+    expect(dataGridSource).toMatch(/function resolvedColumnComment\(column: string, actualColIdx: number\)[\s\S]*?dataGridColumnCommentFor\([\s\S]*?props\.sourceColumns\?\.\[actualColIdx\][\s\S]*?\);\s*\}/);
+    expect(dataGridSource).toContain(':column-comment="headerColumnComment(col.name, col.actualColIdx)"');
+    expect(dataGridSource).toContain(':tooltip-column-comment="resolvedColumnComment(col.name, col.actualColIdx)"');
+    expect(dataGridSource).toContain("(column, index) => headerColumnComment(column, index)");
+  });
+});

apps/desktop/src/lib/__tests__/dataGridColumnLookup.spec.ts

@@ -1,5 +1,25 @@
 import { describe, expect, it } from "vitest";
-import { buildDataGridColumnLookupItems, filterDataGridColumnLookupItems } from "@/lib/dataGrid/dataGridColumnLookup";
+import { buildDataGridColumnLookupItems, dataGridColumnCommentFor, filterDataGridColumnLookupItems } from "@/lib/dataGrid/dataGridColumnLookup";
+
+describe("data grid column comment lookup", () => {
+  it("resolves comments through the physical source column before the result label", () => {
+    const comments = new Map([
+      ["minx", "Minimum X coordinate"],
+      ["MINX", "Result label comment"],
+    ]);
+
+    expect(dataGridColumnCommentFor(comments, "MINX", "minx")).toBe("Minimum X coordinate");
+  });
+
+  it("falls back past blank source comments and case-normalizes result labels", () => {
+    const comments = new Map([
+      ["physical_name", "   "],
+      ["result_name", "Result comment"],
+    ]);
+
+    expect(dataGridColumnCommentFor(comments, "RESULT_NAME", "physical_name")).toBe("Result comment");
+  });
+});
 
 describe("data grid column lookup search", () => {
   const items = buildDataGridColumnLookupItems({