@databricks/appkit 0.41.4 → 0.41.6

package/dist/type-generator/mv-registry/render-types.js

@@ -0,0 +1,118 @@
+//#region src/type-generator/mv-registry/render-types.ts
+/**
+* @todo unify with query-registry.ts
+* Map a Databricks SQL type to a TypeScript primitive.
+* Centralized here (not imported from query-registry) so this module
+* stays self-contained.
+*/
+function tsTypeFor(sqlType) {
+	switch (sqlType.toUpperCase().replace(/\(.*\)$/, "").replace(/<.*>$/, "").split(" ")[0]) {
+		case "BOOLEAN": return "boolean";
+		case "TINYINT":
+		case "SMALLINT":
+		case "INT":
+		case "INTEGER":
+		case "BIGINT":
+		case "FLOAT":
+		case "DOUBLE":
+		case "DECIMAL":
+		case "NUMERIC": return "number";
+		default: return "string";
+	}
+}
+function renderMetricEntry(schema) {
+	if (schema.degraded) return renderDegradedMetricEntry(schema);
+	const indent = "      ";
+	const colsBlock = (cols) => {
+		if (cols.length === 0) return "Record<string, never>";
+		return `{
+${cols.map((col) => {
+			const grainComment = col.timeGrains?.length ? ` @timeGrain ${col.timeGrains.join("|")}` : "";
+			return `${indent}/** @sqlType ${col.type.replace(/\*\//g, "* /")}${grainComment} */
+${indent}${JSON.stringify(col.name)}: ${tsTypeFor(col.type)}`;
+		}).join(";\n")};
+    }`;
+	};
+	const unionOf = (keys) => keys.length > 0 ? keys.join(" | ") : "never";
+	const measuresBlock = colsBlock(schema.measures);
+	const dimensionsBlock = colsBlock(schema.dimensions);
+	const measureUnion = unionOf(schema.measures.map((m) => JSON.stringify(m.name)));
+	const dimensionUnion = unionOf(schema.dimensions.map((d) => JSON.stringify(d.name)));
+	const timeGrainSet = /* @__PURE__ */ new Set();
+	for (const d of schema.dimensions) for (const g of d.timeGrains ?? []) timeGrainSet.add(g);
+	const timeGrainUnion = timeGrainSet.size > 0 ? [...timeGrainSet].sort().map((g) => JSON.stringify(g)).join(" | ") : "never";
+	const measureMetadata = renderMetadataMap(schema.measures, indent);
+	const dimensionMetadata = renderMetadataMap(schema.dimensions, indent, true);
+	return `    ${JSON.stringify(schema.key)}: {
+      key: ${JSON.stringify(schema.key)};
+      source: ${JSON.stringify(schema.source)};
+      lane: ${JSON.stringify(schema.lane)};
+      measures: ${measuresBlock};
+      dimensions: ${dimensionsBlock};
+      measureKeys: ${measureUnion};
+      dimensionKeys: ${dimensionUnion};
+      timeGrains: ${timeGrainUnion};
+      metadata: {
+        measures: ${measureMetadata};
+        dimensions: ${dimensionMetadata};
+      };
+    }`;
+}
+function renderDegradedMetricEntry(schema) {
+	return `    /** Degraded: schema unavailable at type-generation time — permissive types until a successful DESCRIBE refreshes them. */
+    ${JSON.stringify(schema.key)}: {
+      key: ${JSON.stringify(schema.key)};
+      source: ${JSON.stringify(schema.source)};
+      lane: ${JSON.stringify(schema.lane)};
+      measures: Record<string, unknown>;
+      dimensions: Record<string, unknown>;
+      measureKeys: string;
+      dimensionKeys: string;
+      timeGrains: string;
+      metadata: {
+        measures: Record<string, never>;
+        dimensions: Record<string, never>;
+      };
+    }`;
+}
+function renderMetadataMap(cols, indent, includeTimeGrain = false) {
+	if (cols.length === 0) return "Record<string, never>";
+	return `{
+${cols.map((col) => {
+		const fields = [`type: ${JSON.stringify(col.type)}`];
+		if (col.displayName) fields.push(`display_name: ${JSON.stringify(col.displayName)}`);
+		if (col.format) fields.push(`format: ${JSON.stringify(col.format)}`);
+		if (col.description) fields.push(`description: ${JSON.stringify(col.description)}`);
+		if (includeTimeGrain && col.timeGrains && col.timeGrains.length > 0) {
+			const grainTuple = col.timeGrains.map((g) => JSON.stringify(g)).join(", ");
+			fields.push(`time_grain: readonly [${grainTuple}]`);
+		}
+		const fieldsBlock = fields.map((f) => `${indent}  ${f}`).join(";\n");
+		return `${indent}${JSON.stringify(col.name)}: {
+${fieldsBlock};
+${indent}}`;
+	}).join(";\n")};
+    }`;
+}
+function renderMetricRegistry(schemas) {
+	if (schemas.length === 0) return `declare module "@databricks/appkit-ui/react" {
+  interface MetricRegistry {}
+}
+`;
+	return `declare module "@databricks/appkit-ui/react" {
+  interface MetricRegistry {
+${schemas.map(renderMetricEntry).join(";\n")};
+  }
+}
+`;
+}
+function generateMetricTypeDeclarations(schemas) {
+	return `// Auto-generated by AppKit - DO NOT EDIT
+// Generated by 'npx @databricks/appkit generate-types' or Vite plugin during build
+import "@databricks/appkit-ui/react";
+${renderMetricRegistry(schemas)}`;
+}
+
+//#endregion
+export { generateMetricTypeDeclarations };
+//# sourceMappingURL=render-types.js.map

package/dist/type-generator/mv-registry/render-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-types.js","names":[],"sources":["../../../src/type-generator/mv-registry/render-types.ts"],"sourcesContent":["import type { MetricColumnMetadata, MetricSchema } from \"./types\";\n\n/**\n * @todo unify with query-registry.ts\n * Map a Databricks SQL type to a TypeScript primitive.\n * Centralized here (not imported from query-registry) so this module\n * stays self-contained.\n */\nfunction tsTypeFor(sqlType: string): string {\n  const normalized = sqlType\n    .toUpperCase()\n    .replace(/\\(.*\\)$/, \"\")\n    .replace(/<.*>$/, \"\")\n    .split(\" \")[0];\n\n  switch (normalized) {\n    case \"BOOLEAN\":\n      return \"boolean\";\n    case \"TINYINT\":\n    case \"SMALLINT\":\n    case \"INT\":\n    case \"INTEGER\":\n    case \"BIGINT\":\n    case \"FLOAT\":\n    case \"DOUBLE\":\n    case \"DECIMAL\":\n    case \"NUMERIC\":\n      return \"number\";\n    default:\n      return \"string\";\n  }\n}\n\n// Render a MetricRegistry interface entry from a MetricSchema.\nfunction renderMetricEntry(schema: MetricSchema): string {\n  if (schema.degraded) {\n    return renderDegradedMetricEntry(schema);\n  }\n  const indent = \"      \";\n  const colsBlock = (cols: MetricColumnMetadata[]): string => {\n    if (cols.length === 0) return \"Record<string, never>\";\n    const fields = cols\n      .map((col) => {\n        const grainComment = col.timeGrains?.length\n          ? ` @timeGrain ${col.timeGrains.join(\"|\")}`\n          : \"\";\n        return `${indent}/** @sqlType ${col.type.replace(/\\*\\//g, \"* /\")}${grainComment} */\n${indent}${JSON.stringify(col.name)}: ${tsTypeFor(col.type)}`;\n      })\n      .join(\";\\n\");\n    return `{\n${fields};\n    }`;\n  };\n  const unionOf = (keys: string[]): string =>\n    keys.length > 0 ? keys.join(\" | \") : \"never\";\n\n  const measuresBlock = colsBlock(schema.measures);\n  const dimensionsBlock = colsBlock(schema.dimensions);\n  const measureUnion = unionOf(\n    schema.measures.map((m) => JSON.stringify(m.name)),\n  );\n  const dimensionUnion = unionOf(\n    schema.dimensions.map((d) => JSON.stringify(d.name)),\n  );\n\n  const timeGrainSet = new Set<string>();\n  for (const d of schema.dimensions) {\n    for (const g of d.timeGrains ?? []) {\n      timeGrainSet.add(g);\n    }\n  }\n  const timeGrainUnion =\n    timeGrainSet.size > 0\n      ? [...timeGrainSet]\n          .sort()\n          .map((g) => JSON.stringify(g))\n          .join(\" | \")\n      : \"never\";\n\n  const measureMetadata = renderMetadataMap(schema.measures, indent);\n  const dimensionMetadata = renderMetadataMap(schema.dimensions, indent, true);\n\n  return `    ${JSON.stringify(schema.key)}: {\n      key: ${JSON.stringify(schema.key)};\n      source: ${JSON.stringify(schema.source)};\n      lane: ${JSON.stringify(schema.lane)};\n      measures: ${measuresBlock};\n      dimensions: ${dimensionsBlock};\n      measureKeys: ${measureUnion};\n      dimensionKeys: ${dimensionUnion};\n      timeGrains: ${timeGrainUnion};\n      metadata: {\n        measures: ${measureMetadata};\n        dimensions: ${dimensionMetadata};\n      };\n    }`;\n}\n\n// Render the permissive (\"degraded-open\") entry for a schema the warehouse could not describe.\nfunction renderDegradedMetricEntry(schema: MetricSchema): string {\n  return `    /** Degraded: schema unavailable at type-generation time — permissive types until a successful DESCRIBE refreshes them. */\n    ${JSON.stringify(schema.key)}: {\n      key: ${JSON.stringify(schema.key)};\n      source: ${JSON.stringify(schema.source)};\n      lane: ${JSON.stringify(schema.lane)};\n      measures: Record<string, unknown>;\n      dimensions: Record<string, unknown>;\n      measureKeys: string;\n      dimensionKeys: string;\n      timeGrains: string;\n      metadata: {\n        measures: Record<string, never>;\n        dimensions: Record<string, never>;\n      };\n    }`;\n}\n\n// Render the type-level shape of a column's semantic-metadata map\n// for the `metadata` field of a MetricRegistry entry.\nfunction renderMetadataMap(\n  cols: MetricColumnMetadata[],\n  indent: string,\n  includeTimeGrain = false,\n): string {\n  if (cols.length === 0) return \"Record<string, never>\";\n\n  const inner = cols\n    .map((col) => {\n      const fields: string[] = [`type: ${JSON.stringify(col.type)}`];\n      if (col.displayName) {\n        fields.push(`display_name: ${JSON.stringify(col.displayName)}`);\n      }\n      if (col.format) {\n        fields.push(`format: ${JSON.stringify(col.format)}`);\n      }\n      if (col.description) {\n        fields.push(`description: ${JSON.stringify(col.description)}`);\n      }\n      if (includeTimeGrain && col.timeGrains && col.timeGrains.length > 0) {\n        const grainTuple = col.timeGrains\n          .map((g) => JSON.stringify(g))\n          .join(\", \");\n        fields.push(`time_grain: readonly [${grainTuple}]`);\n      }\n      const fieldsBlock = fields.map((f) => `${indent}  ${f}`).join(\";\\n\");\n      return `${indent}${JSON.stringify(col.name)}: {\n${fieldsBlock};\n${indent}}`;\n    })\n    .join(\";\\n\");\n\n  return `{\n${inner};\n    }`;\n}\n\n// Render the augmentation block for the appkit-ui MetricRegistry interface.\nfunction renderMetricRegistry(schemas: MetricSchema[]): string {\n  if (schemas.length === 0) {\n    return `declare module \"@databricks/appkit-ui/react\" {\n  interface MetricRegistry {}\n}\n`;\n  }\n  const entries = schemas.map(renderMetricEntry).join(\";\\n\");\n  return `declare module \"@databricks/appkit-ui/react\" {\n  interface MetricRegistry {\n${entries};\n  }\n}\n`;\n}\n\n// Build the full metric.d.ts file from a list of metric schemas.\nexport function generateMetricTypeDeclarations(\n  schemas: MetricSchema[],\n): string {\n  return `// Auto-generated by AppKit - DO NOT EDIT\n// Generated by 'npx @databricks/appkit generate-types' or Vite plugin during build\nimport \"@databricks/appkit-ui/react\";\n${renderMetricRegistry(schemas)}`;\n}\n"],"mappings":"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"}

package/dist/type-generator/mv-registry/sync.js

@@ -0,0 +1,96 @@
+import { getErrorDiagnostic, isConnectivityError } from "../errors.js";
+import { extractMetricColumns, parseDescribeTableExtendedJson } from "./describe.js";
+
+//#region src/type-generator/mv-registry/sync.ts
+/**
+* Build the degraded schema emitted when an entry's columns are not
+* available — same key/source/lane as a real schema, with empty
+* measure/dimension allowlists and `degraded: true`.
+*/
+function emptyMetricSchema(entry) {
+	return {
+		key: entry.key,
+		source: entry.source,
+		lane: entry.lane,
+		measures: [],
+		dimensions: [],
+		degraded: true
+	};
+}
+const MV_DESCRIBE_CONCURRENCY = 10;
+/**
+* Run schema synchronization for every entry in `metric-views.json`.
+*/
+async function syncMetrics(resolution, fetcher) {
+	const { entries } = resolution;
+	const schemas = new Array(entries.length);
+	const failureSlots = new Array(entries.length);
+	const failedOutcome = (index, entry, reason, transient) => ({
+		index,
+		schema: emptyMetricSchema(entry),
+		failure: {
+			key: entry.key,
+			source: entry.source,
+			reason,
+			transient
+		}
+	});
+	const describeOne = async (entry, index) => {
+		let response;
+		try {
+			response = await fetcher(entry.source);
+		} catch (err) {
+			return failedOutcome(index, entry, `DESCRIBE TABLE EXTENDED failed: ${getErrorDiagnostic(err)}`, isConnectivityError(err));
+		}
+		const state = response.status?.state;
+		if (state !== "SUCCEEDED" && state !== "FAILED") return {
+			index,
+			schema: emptyMetricSchema(entry)
+		};
+		let columns;
+		try {
+			columns = extractMetricColumns(parseDescribeTableExtendedJson(response));
+		} catch (err) {
+			return failedOutcome(index, entry, `Failed to extract columns from DESCRIBE response: ${err.message}`, false);
+		}
+		if (columns.length === 0) return failedOutcome(index, entry, "DESCRIBE response yielded zero columns — check the response shape (top-level `columns` array or `schema.fields`).", false);
+		const measures = columns.filter((c) => c.isMeasure);
+		const dimensions = columns.filter((c) => !c.isMeasure);
+		return {
+			index,
+			schema: {
+				key: entry.key,
+				source: entry.source,
+				lane: entry.lane,
+				measures,
+				dimensions
+			}
+		};
+	};
+	for (let offset = 0; offset < entries.length; offset += MV_DESCRIBE_CONCURRENCY) {
+		const slice = entries.slice(offset, offset + MV_DESCRIBE_CONCURRENCY);
+		const settled = await Promise.allSettled(slice.map((entry, i) => describeOne(entry, offset + i)));
+		for (let i = 0; i < settled.length; i++) {
+			const result = settled[i];
+			if (result.status === "fulfilled") {
+				const { index, schema, failure } = result.value;
+				schemas[index] = schema;
+				if (failure) failureSlots[index] = failure;
+			} else {
+				const index = offset + i;
+				const entry = entries[index];
+				const { schema, failure } = failedOutcome(index, entry, `DESCRIBE TABLE EXTENDED failed: ${getErrorDiagnostic(result.reason)}`, isConnectivityError(result.reason));
+				schemas[index] = schema;
+				failureSlots[index] = failure;
+			}
+		}
+	}
+	return {
+		schemas,
+		failures: failureSlots.filter((failure) => failure !== void 0)
+	};
+}
+
+//#endregion
+export { emptyMetricSchema, syncMetrics };
+//# sourceMappingURL=sync.js.map

package/dist/type-generator/mv-registry/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","names":[],"sources":["../../../src/type-generator/mv-registry/sync.ts"],"sourcesContent":["import { getErrorDiagnostic, isConnectivityError } from \"../errors\";\nimport type { DatabricksStatementExecutionResponse } from \"../types\";\nimport {\n  extractMetricColumns,\n  parseDescribeTableExtendedJson,\n} from \"./describe\";\nimport type {\n  DescribeFetcher,\n  MetricColumnMetadata,\n  MetricConfigResolution,\n  MetricSchema,\n  MetricSyncFailure,\n  MetricSyncResult,\n  ResolvedMetricEntry,\n} from \"./types\";\n\n/**\n * Build the degraded schema emitted when an entry's columns are not\n * available — same key/source/lane as a real schema, with empty\n * measure/dimension allowlists and `degraded: true`.\n */\nexport function emptyMetricSchema(\n  entry: Pick<MetricSchema, \"key\" | \"source\" | \"lane\">,\n): MetricSchema {\n  return {\n    key: entry.key,\n    source: entry.source,\n    lane: entry.lane,\n    measures: [],\n    dimensions: [],\n    degraded: true,\n  };\n}\n\n// Maximum number of in-flight DESCRIBE statements per syncMetrics pass.\nconst MV_DESCRIBE_CONCURRENCY = 10;\n\n// Outcome of describing a single metric entry.\ninterface MetricDescribeOutcome {\n  index: number;\n  schema: MetricSchema;\n  failure?: MetricSyncFailure;\n}\n\n/**\n * Run schema synchronization for every entry in `metric-views.json`.\n */\nexport async function syncMetrics(\n  resolution: MetricConfigResolution,\n  fetcher: DescribeFetcher,\n): Promise<MetricSyncResult> {\n  const { entries } = resolution;\n  const schemas = new Array<MetricSchema>(entries.length);\n  const failureSlots = new Array<MetricSyncFailure | undefined>(entries.length);\n\n  const failedOutcome = (\n    index: number,\n    entry: ResolvedMetricEntry,\n    reason: string,\n    transient: boolean,\n  ): MetricDescribeOutcome => ({\n    index,\n    schema: emptyMetricSchema(entry),\n    failure: { key: entry.key, source: entry.source, reason, transient },\n  });\n\n  const describeOne = async (\n    entry: ResolvedMetricEntry,\n    index: number,\n  ): Promise<MetricDescribeOutcome> => {\n    let response: DatabricksStatementExecutionResponse;\n    try {\n      response = await fetcher(entry.source);\n    } catch (err) {\n      const reason = `DESCRIBE TABLE EXTENDED failed: ${getErrorDiagnostic(err)}`;\n      // Connectivity blips self-converge (retry next pass); auth, a bad\n      // warehouse id, a truncated / multi-chunk result, or a malformed request\n      // are deterministic and must surface — the same split the query path makes.\n      return failedOutcome(index, entry, reason, isConnectivityError(err));\n    }\n\n    const state = response.status?.state;\n    if (state !== \"SUCCEEDED\" && state !== \"FAILED\") {\n      return { index, schema: emptyMetricSchema(entry) };\n    }\n\n    let columns: MetricColumnMetadata[];\n    try {\n      const parsed = parseDescribeTableExtendedJson(response);\n      columns = extractMetricColumns(parsed);\n    } catch (err) {\n      const reason = `Failed to extract columns from DESCRIBE response: ${(err as Error).message}`;\n      return failedOutcome(index, entry, reason, false);\n    }\n\n    if (columns.length === 0) {\n      const reason =\n        \"DESCRIBE response yielded zero columns — check the response shape (top-level `columns` array or `schema.fields`).\";\n      return failedOutcome(index, entry, reason, false);\n    }\n\n    const measures = columns.filter((c) => c.isMeasure);\n    const dimensions = columns.filter((c) => !c.isMeasure);\n\n    return {\n      index,\n      schema: {\n        key: entry.key,\n        source: entry.source,\n        lane: entry.lane,\n        measures,\n        dimensions,\n      },\n    };\n  };\n\n  for (\n    let offset = 0;\n    offset < entries.length;\n    offset += MV_DESCRIBE_CONCURRENCY\n  ) {\n    const slice = entries.slice(offset, offset + MV_DESCRIBE_CONCURRENCY);\n    const settled = await Promise.allSettled(\n      slice.map((entry, i) => describeOne(entry, offset + i)),\n    );\n\n    for (let i = 0; i < settled.length; i++) {\n      const result = settled[i];\n      if (result.status === \"fulfilled\") {\n        const { index, schema, failure } = result.value;\n        schemas[index] = schema;\n        if (failure) {\n          failureSlots[index] = failure;\n        }\n      } else {\n        const index = offset + i;\n        const entry = entries[index];\n        const { schema, failure } = failedOutcome(\n          index,\n          entry,\n          `DESCRIBE TABLE EXTENDED failed: ${getErrorDiagnostic(result.reason)}`,\n          isConnectivityError(result.reason),\n        );\n        schemas[index] = schema;\n        failureSlots[index] = failure;\n      }\n    }\n  }\n\n  const failures = failureSlots.filter(\n    (failure): failure is MetricSyncFailure => failure !== undefined,\n  );\n\n  return { schemas, failures };\n}\n"],"mappings":";;;;;;;;;AAqBA,SAAgB,kBACd,OACc;AACd,QAAO;EACL,KAAK,MAAM;EACX,QAAQ,MAAM;EACd,MAAM,MAAM;EACZ,UAAU,EAAE;EACZ,YAAY,EAAE;EACd,UAAU;EACX;;AAIH,MAAM,0BAA0B;;;;AAYhC,eAAsB,YACpB,YACA,SAC2B;CAC3B,MAAM,EAAE,YAAY;CACpB,MAAM,UAAU,IAAI,MAAoB,QAAQ,OAAO;CACvD,MAAM,eAAe,IAAI,MAAqC,QAAQ,OAAO;CAE7E,MAAM,iBACJ,OACA,OACA,QACA,eAC2B;EAC3B;EACA,QAAQ,kBAAkB,MAAM;EAChC,SAAS;GAAE,KAAK,MAAM;GAAK,QAAQ,MAAM;GAAQ;GAAQ;GAAW;EACrE;CAED,MAAM,cAAc,OAClB,OACA,UACmC;EACnC,IAAI;AACJ,MAAI;AACF,cAAW,MAAM,QAAQ,MAAM,OAAO;WAC/B,KAAK;AAKZ,UAAO,cAAc,OAAO,OAJb,mCAAmC,mBAAmB,IAAI,IAI9B,oBAAoB,IAAI,CAAC;;EAGtE,MAAM,QAAQ,SAAS,QAAQ;AAC/B,MAAI,UAAU,eAAe,UAAU,SACrC,QAAO;GAAE;GAAO,QAAQ,kBAAkB,MAAM;GAAE;EAGpD,IAAI;AACJ,MAAI;AAEF,aAAU,qBADK,+BAA+B,SAAS,CACjB;WAC/B,KAAK;AAEZ,UAAO,cAAc,OAAO,OADb,qDAAsD,IAAc,WACxC,MAAM;;AAGnD,MAAI,QAAQ,WAAW,EAGrB,QAAO,cAAc,OAAO,OAD1B,qHACyC,MAAM;EAGnD,MAAM,WAAW,QAAQ,QAAQ,MAAM,EAAE,UAAU;EACnD,MAAM,aAAa,QAAQ,QAAQ,MAAM,CAAC,EAAE,UAAU;AAEtD,SAAO;GACL;GACA,QAAQ;IACN,KAAK,MAAM;IACX,QAAQ,MAAM;IACd,MAAM,MAAM;IACZ;IACA;IACD;GACF;;AAGH,MACE,IAAI,SAAS,GACb,SAAS,QAAQ,QACjB,UAAU,yBACV;EACA,MAAM,QAAQ,QAAQ,MAAM,QAAQ,SAAS,wBAAwB;EACrE,MAAM,UAAU,MAAM,QAAQ,WAC5B,MAAM,KAAK,OAAO,MAAM,YAAY,OAAO,SAAS,EAAE,CAAC,CACxD;AAED,OAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;GACvC,MAAM,SAAS,QAAQ;AACvB,OAAI,OAAO,WAAW,aAAa;IACjC,MAAM,EAAE,OAAO,QAAQ,YAAY,OAAO;AAC1C,YAAQ,SAAS;AACjB,QAAI,QACF,cAAa,SAAS;UAEnB;IACL,MAAM,QAAQ,SAAS;IACvB,MAAM,QAAQ,QAAQ;IACtB,MAAM,EAAE,QAAQ,YAAY,cAC1B,OACA,OACA,mCAAmC,mBAAmB,OAAO,OAAO,IACpE,oBAAoB,OAAO,OAAO,CACnC;AACD,YAAQ,SAAS;AACjB,iBAAa,SAAS;;;;AAS5B,QAAO;EAAE;EAAS,UAJD,aAAa,QAC3B,YAA0C,YAAY,OACxD;EAE2B"}

package/dist/type-generator/query-registry.js

@@ -1,5 +1,7 @@
 import { createLogger } from "../logging/logger.js";
 import { CACHE_VERSION, hashSQL, loadCache, saveCache } from "./cache.js";
+import { getErrorDiagnostic, isConnectivityError } from "./errors.js";
+import { describeAdaptive } from "./statement-result.js";
 import { decidePreflight } from "./preflight.js";
 import { Spinner } from "./spinner.js";
 import { sqlTypeToHelper, sqlTypeToMarker } from "./types.js";
@@ -66,83 +68,6 @@ function parseError(raw) {
 	} catch {}
 	return { message: raw };
 }
-function isObject(value) {
-	return typeof value === "object" && value !== null;
-}
-function getErrorMessage(error) {
-	if (error instanceof Error) return error.message;
-	if (isObject(error) && typeof error.message === "string") return error.message;
-	return String(error);
-}
-function getErrorDiagnostic(error) {
-	const seen = /* @__PURE__ */ new Set();
-	const messages = [];
-	const stack = [error];
-	while (stack.length > 0) {
-		const current = stack.pop();
-		if (current === void 0 || seen.has(current)) continue;
-		seen.add(current);
-		const message = getErrorMessage(current);
-		if (message && message !== "[object Object]" && !messages.includes(message)) messages.push(message);
-		const code = getErrorCode(current);
-		if (code && !messages.includes(code)) messages.push(code);
-		stack.push(...getErrorChildren(current));
-	}
-	return messages.length > 0 ? messages.join(": ") : getErrorMessage(error);
-}
-function getErrorCode(error) {
-	if (!isObject(error)) return void 0;
-	const code = error.code ?? error.errno;
-	return typeof code === "string" ? code : void 0;
-}
-function getErrorStatus(error) {
-	if (!isObject(error)) return void 0;
-	const direct = error.status ?? error.statusCode;
-	if (typeof direct === "number") return direct;
-	if (isObject(error.response) && typeof error.response.status === "number") return error.response.status;
-}
-function getErrorChildren(error) {
-	if (!isObject(error)) return [];
-	const children = [];
-	if ("cause" in error) children.push(error.cause);
-	if (error instanceof AggregateError) children.push(...error.errors);
-	return children;
-}
-const CONNECTIVITY_ERROR_CODES = new Set([
-	"ECONNREFUSED",
-	"ECONNRESET",
-	"ENOTFOUND",
-	"ETIMEDOUT",
-	"EAI_AGAIN",
-	"EAI_NODATA",
-	"EAI_NONAME",
-	"EHOSTUNREACH",
-	"ENETUNREACH",
-	"CERT_HAS_EXPIRED",
-	"DEPTH_ZERO_SELF_SIGNED_CERT",
-	"ERR_TLS_CERT_ALTNAME_INVALID",
-	"SELF_SIGNED_CERT_IN_CHAIN",
-	"UNABLE_TO_VERIFY_LEAF_SIGNATURE"
-]);
-function isConnectivityMessage(message) {
-	return /\bconnection (?:refused|reset|timed out)\b/i.test(message) || /\bsocket hang up\b/i.test(message) || /\bnetwork error\b/i.test(message) || /\bcan'?t connect to\b/i.test(message) || /\bcertificate has expired\b/i.test(message) || /\bunable to verify the first certificate\b/i.test(message) || /\bupstream connect error or disconnect\/reset before headers\b/i.test(message);
-}
-function isConnectivityError(error) {
-	const seen = /* @__PURE__ */ new Set();
-	const stack = [error];
-	while (stack.length > 0) {
-		const current = stack.pop();
-		if (current === void 0 || seen.has(current)) continue;
-		seen.add(current);
-		const code = getErrorCode(current);
-		if (code && (CONNECTIVITY_ERROR_CODES.has(code) || code.startsWith("UND_ERR_"))) return true;
-		const status = getErrorStatus(current);
-		if (status === 502 || status === 503 || status === 504) return true;
-		if (isConnectivityMessage(getErrorMessage(current))) return true;
-		stack.push(...getErrorChildren(current));
-	}
-	return false;
-}
 /**
 * Extract parameters from a SQL query
 * @param sql - the SQL query to extract parameters from
@@ -180,7 +105,7 @@ function convertToQueryType(result, sql, queryName) {
 	const resultFields = columns.map((column) => {
 		const mappedType = typeMap[normalizeTypeName(column.type_name)] || "unknown";
 		const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name) ? column.name : `"${column.name}"`;
-		return `${column.comment ? `/** ${column.comment} */\n      ` : `/** @sqlType ${column.type_name} */\n      `}${name}: ${mappedType}`;
+		return `${column.comment ? `/** ${column.comment.replace(/\*\//g, "* /")} */\n      ` : `/** @sqlType ${column.type_name.replace(/\*\//g, "* /")} */\n      `}${name}: ${mappedType}`;
 	});
 	const hasResults = resultFields.length > 0;
 	return {
@@ -215,9 +140,11 @@ function degradedType(cache, queryName, sql, sqlHash) {
 	const prior = cache.queries[queryName];
 	return prior?.hash === sqlHash && !prior.retry ? prior.type : generateUnknownResultQuery(sql, queryName);
 }
+const PARAM_TYPE_ALTERNATION = "STRING|NUMERIC|DECIMAL|BIGINT|TINYINT|SMALLINT|INT|FLOAT|DOUBLE|BOOLEAN|DATE|TIMESTAMP_NTZ|TIMESTAMP|BINARY";
 function extractParameterTypes(sql) {
 	const paramTypes = {};
-	const matches = sql.matchAll(/--\s*@param\s+(\w+)\s+(STRING|NUMERIC|DECIMAL|BIGINT|TINYINT|SMALLINT|INT|FLOAT|DOUBLE|BOOLEAN|DATE|TIMESTAMP_NTZ|TIMESTAMP|BINARY)\b/gi);
+	const regex = new RegExp(`--\\s*@param\\s+(\\w+)\\s+(${PARAM_TYPE_ALTERNATION})\\b`, "gi");
+	const matches = sql.matchAll(regex);
 	for (const match of matches) {
 		const [, paramName, paramType] = match;
 		paramTypes[paramName] = paramType.toUpperCase();
@@ -244,6 +171,120 @@ function defaultForType(sqlType) {
 	}
 }
 /**
+* True when `raw` is already a single, well-formed SQL single-quoted string
+* literal — i.e. it opens and closes with `'` and every interior quote is part
+* of an escaped `''` pair. `'2024-01-01'` and `'O''Brien'` qualify;
+* `'a' OR 1=1 OR 'b'` does not (it has lone interior quotes), so it is treated
+* as raw content and re-escaped rather than trusted. A backslash also
+* disqualifies it: Databricks/Spark treats `\` as an escape inside literals (so
+* `'a\'` is unterminated), and we never trust such input — it is re-escaped.
+*/
+function isWellFormedStringLiteral(raw) {
+	if (raw.length < 2 || !raw.startsWith("'") || !raw.endsWith("'")) return false;
+	const inner = raw.slice(1, -1);
+	if (inner.includes("\\")) return false;
+	return !inner.replace(/''/g, "").includes("'");
+}
+/**
+* Format a user-supplied sample value as a SQL literal for substitution into
+* the build-time DESCRIBE statement. Returns `null` when the value isn't valid
+* for its type, so the caller falls back to the safe type-based placeholder
+* instead of substituting attacker-controllable text.
+*
+* The value comes from a `.sql` file that may be shared via a template or
+* dependency, so it must not be able to inject SQL into `DESCRIBE QUERY`:
+* - string-like types are always emitted as one well-formed, fully-escaped
+*   single-quoted literal (a pre-quoted literal is kept as-is, anything else is
+*   quoted with both `\` and `'` doubled so neither can terminate the literal),
+*   so the value can never break out of the string;
+* - numeric / boolean / binary values must match a strict literal shape and are
+*   rejected (`null`) otherwise, rather than being passed through verbatim.
+*/
+function formatSampleValue(sqlType, raw) {
+	switch (sqlType?.toUpperCase()) {
+		case "STRING":
+		case "DATE":
+		case "TIMESTAMP":
+		case "TIMESTAMP_NTZ": return isWellFormedStringLiteral(raw) ? raw : `'${raw.replace(/\\/g, "\\\\").replace(/'/g, "''")}'`;
+		case "NUMERIC":
+		case "DECIMAL":
+		case "BIGINT":
+		case "TINYINT":
+		case "SMALLINT":
+		case "INT":
+		case "FLOAT":
+		case "DOUBLE": return /^[+-]?\d+(\.\d+)?$/.test(raw) ? raw : null;
+		case "BOOLEAN": return /^(?:true|false)$/i.test(raw) ? raw.toLowerCase() : null;
+		case "BINARY": return /^X'[0-9a-fA-F]*'$/i.test(raw) ? raw : null;
+		default: return null;
+	}
+}
+/**
+* Parse optional describe-time sample values from `@param` annotations, e.g.
+* `-- @param target_catalog STRING = main`. The value is substituted into the
+* SQL **only during DESCRIBE QUERY** so type generation can resolve queries
+* whose shape depends on a parameter value — most notably dynamic table names
+* via `IDENTIFIER(:target_catalog || '.schema.table')`, where the empty-string
+* default would otherwise produce malformed SQL. Runtime binding is unaffected:
+* the analytics plugin still binds the real parameter at execution time, so the
+* query stays portable across environments.
+*
+* Returns a map of parameter name to the formatted SQL literal to substitute.
+*/
+function extractParameterDefaults(sql) {
+	const defaults = {};
+	const regex = new RegExp(`--[^\\S\\r\\n]*@param[^\\S\\r\\n]+(\\w+)[^\\S\\r\\n]+(${PARAM_TYPE_ALTERNATION})[^\\S\\r\\n]*=[^\\S\\r\\n]*(.+?)[^\\S\\r\\n]*$`, "gim");
+	for (const match of sql.matchAll(regex)) {
+		const [, paramName, paramType, rawValue] = match;
+		const formatted = formatSampleValue(paramType, rawValue);
+		if (formatted !== null) defaults[paramName] = formatted;
+	}
+	return defaults;
+}
+/**
+* Replace `:param` placeholders with describe-time literals so `DESCRIBE QUERY`
+* can run without bound parameters. Resolution order per parameter:
+*   1. An explicit `-- @param name TYPE = value` sample value (wins), which lets
+*      dynamic table names via `IDENTIFIER(...)` resolve to a real table.
+*   2. Otherwise a placeholder default derived from the annotated/inferred type.
+* Placeholders inside string literals or comments are left untouched.
+*/
+function substituteParametersForDescribe(sql) {
+	const protectedRanges = getProtectedRanges(sql);
+	const annotatedTypes = extractParameterTypes(sql);
+	const parameterTypes = {
+		...inferParameterTypes(sql, protectedRanges),
+		...annotatedTypes
+	};
+	const parameterDefaults = extractParameterDefaults(sql);
+	return sql.replace(/(?<!:):([a-zA-Z_]\w*)/g, (original, paramName, offset) => {
+		if (isInsideProtectedRange(offset, protectedRanges)) return original;
+		const sampleValue = parameterDefaults[paramName];
+		if (sampleValue !== void 0) return sampleValue;
+		return defaultForType(parameterTypes[paramName]);
+	});
+}
+/**
+* Append a remediation hint when a DESCRIBE failure looks like a dynamic
+* identifier that couldn't be resolved: the query calls `IDENTIFIER(...)` and
+* has at least one parameter without a describe-time sample value. These fail
+* because typegen substitutes a placeholder default (e.g. `''`) that yields a
+* malformed or non-existent table name. Steering the user to the `= value`
+* annotation turns the fatal error into a one-line fix.
+*/
+function withIdentifierHint(error, sql) {
+	if (!/\bIDENTIFIER\s*\(/i.test(sql)) return error;
+	const params = extractParameters(sql, getProtectedRanges(sql));
+	const defaults = extractParameterDefaults(sql);
+	const unresolved = params.filter((p) => !SERVER_INJECTED_PARAMS.includes(p) && defaults[p] === void 0);
+	if (unresolved.length === 0) return error;
+	const example = unresolved[0];
+	return {
+		...error,
+		message: `${error.message}\n  Hint: this query uses IDENTIFIER() with parameter(s) ${unresolved.map((p) => `:${p}`).join(", ")}. Give type generation a sample value so it can resolve the table, e.g. \`-- @param ${example} STRING = my_catalog\`. The runtime query still binds the real parameter.`
+	};
+}
+/**
 * Infer parameter types from positional context in SQL.
 * V1 only infers NUMERIC from patterns like LIMIT, OFFSET, TOP,
 * FETCH FIRST ... ROWS, and arithmetic operators.
@@ -310,13 +351,12 @@ async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {
 				...inferParameterTypes(sql, protectedRanges),
 				...annotatedTypes
 			};
-			const sqlWithDefaults = sql.replace(/(?<!:):([a-zA-Z_]\w*)/g, (original, paramName, offset) => {
-				if (isInsideProtectedRange(offset, protectedRanges)) return original;
-				return defaultForType(parameterTypes[paramName]);
-			});
+			const parameterDefaults = extractParameterDefaults(sql);
+			const sqlWithDefaults = substituteParametersForDescribe(sql);
 			const allParams = extractParameters(sql, protectedRanges);
 			for (const param of allParams) {
 				if (SERVER_INJECTED_PARAMS.includes(param)) continue;
+				if (parameterDefaults[param]) continue;
 				if (parameterTypes[param]) continue;
 				logger.warn("%s: parameter \":%s\" has no type annotation or inference. Add %s to the query file.", queryFiles[i], param, `-- @param ${param} <TYPE>`);
 			}
@@ -399,11 +439,9 @@ async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {
 			let completed = 0;
 			const total = uncachedQueries.length;
 			spinner.start(`Describing ${total} ${total === 1 ? "query" : "queries"} (0/${total})`);
+			const describeFormat = {};
 			const describeOne = async ({ index, queryName, sql, sqlHash, cleanedSql }) => {
-				const result = await client.statementExecution.executeStatement({
-					statement: `DESCRIBE QUERY ${cleanedSql}`,
-					warehouse_id: warehouseId
-				});
+				const result = await describeAdaptive(client, `DESCRIBE QUERY ${cleanedSql}`, warehouseId, describeFormat);
 				completed++;
 				spinner.update(`Describing ${total} ${total === 1 ? "query" : "queries"} (${completed}/${total})`);
 				logger.debug("DESCRIBE result for %s: state=%s, rows=%d", queryName, result.status.state, result.result?.data_array?.length ?? 0);
@@ -416,7 +454,7 @@ async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {
 							name: queryName,
 							type: generateUnknownResultQuery(sql, queryName)
 						},
-						error: parseError(sqlError)
+						error: withIdentifierHint(parseError(sqlError), sql)
 					};
 				}
 				if (result.status.state !== "SUCCEEDED") return {