@databricks/appkit 0.41.5 → 0.41.7

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

@@ -1 +1 @@
-{"version":3,"file":"query-registry.js","names":[],"sources":["../../src/type-generator/query-registry.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport pc from \"picocolors\";\nimport { createLogger } from \"../logging/logger\";\nimport { CACHE_VERSION, hashSQL, loadCache, saveCache } from \"./cache\";\nimport { decidePreflight, type PreflightMode } from \"./preflight\";\nimport { Spinner } from \"./spinner\";\nimport {\n  type DatabricksStatementExecutionResponse,\n  type QueryFatalError,\n  type QueryGenerationResult,\n  type QuerySchema,\n  type QuerySyntaxError,\n  sqlTypeToHelper,\n  sqlTypeToMarker,\n} from \"./types\";\nimport {\n  getWarehouseState,\n  startWarehouse,\n  waitUntilRunning,\n} from \"./warehouse-status\";\n\nconst logger = createLogger(\"type-generator:query-registry\");\n\n/**\n * Upper bound on how long a `blocking`-mode preflight will wait for a starting\n * warehouse to reach RUNNING before giving up (~5 min). Generous enough to ride\n * out a cold start without hanging an interactive CLI invocation indefinitely.\n */\nconst PREFLIGHT_WAIT_MAX_MS = 300_000;\n\n/**\n * Regex breakdown:\n *   '(?:[^']|'')*'   — matches a SQL string literal, including escaped '' pairs\n *   |                 — alternation: whichever branch matches first at a position wins\n *   --[^\\n]*          — matches a single-line SQL comment\n *\n * Because the regex engine scans left-to-right, a `'` is consumed as a string\n * literal before any `--` inside it could match as a comment — giving us\n * correct single-pass ordering without a manual state machine.\n *\n * V1: no block-comment support (deferred to next PR).\n */\nconst PROTECTED_RANGE_RE = /'(?:[^']|'')*'|--[^\\n]*/g;\n\n/**\n * Numeric-context patterns for positional type inference.\n * Hoisted to module scope — safe because matchAll() clones the regex internally.\n */\nconst NUMERIC_PATTERNS: RegExp[] = [\n  /\\bLIMIT\\s+:([a-zA-Z_]\\w*)/gi,\n  /\\bOFFSET\\s+:([a-zA-Z_]\\w*)/gi,\n  /\\bTOP\\s+:([a-zA-Z_]\\w*)/gi,\n  /\\bFETCH\\s+FIRST\\s+:([a-zA-Z_]\\w*)\\s+ROWS/gi,\n  // V1 limitation: arithmetic operators may false-positive for date\n  // expressions like `:start_date - INTERVAL '1 day'`. A smarter\n  // heuristic (e.g. look-ahead for INTERVAL) is deferred to a future PR.\n  /[+\\-*/]\\s*:([a-zA-Z_]\\w*)/g,\n  /:([a-zA-Z_]\\w*)\\s*[+\\-*/]/g,\n];\n\nexport function getProtectedRanges(sql: string): Array<[number, number]> {\n  const ranges: Array<[number, number]> = [];\n  for (const m of sql.matchAll(PROTECTED_RANGE_RE)) {\n    ranges.push([m.index, m.index + m[0].length]);\n  }\n  return ranges;\n}\n\nfunction isInsideProtectedRange(\n  offset: number,\n  ranges: Array<[number, number]>,\n): boolean {\n  return ranges.some(([start, end]) => offset >= start && offset < end);\n}\n\n/**\n * Parse a raw API/SDK error into a structured code + message.\n * Handles Databricks-style JSON bodies embedded in the message string,\n * e.g. `Response from server (Bad Request) {\"error_code\":\"...\",\"message\":\"...\"}`.\n */\nfunction parseError(raw: string): { code?: string; message: string } {\n  const jsonMatch = raw.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    try {\n      const parsed = JSON.parse(jsonMatch[0]);\n      if (parsed.error_code || parsed.message) {\n        return {\n          code: parsed.error_code,\n          message: parsed.message || raw,\n        };\n      }\n    } catch {\n      // not valid JSON, fall through\n    }\n  }\n  return { message: raw };\n}\n\nfunction isObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\nfunction getErrorMessage(error: unknown): string {\n  if (error instanceof Error) return error.message;\n  if (isObject(error) && typeof error.message === \"string\") {\n    return error.message;\n  }\n  return String(error);\n}\n\nfunction getErrorDiagnostic(error: unknown): string {\n  const seen = new Set<unknown>();\n  const messages: string[] = [];\n  const stack = [error];\n\n  while (stack.length > 0) {\n    const current = stack.pop();\n    if (current === undefined || seen.has(current)) continue;\n    seen.add(current);\n\n    const message = getErrorMessage(current);\n    if (\n      message &&\n      message !== \"[object Object]\" &&\n      !messages.includes(message)\n    ) {\n      messages.push(message);\n    }\n\n    const code = getErrorCode(current);\n    if (code && !messages.includes(code)) messages.push(code);\n\n    stack.push(...getErrorChildren(current));\n  }\n\n  return messages.length > 0 ? messages.join(\": \") : getErrorMessage(error);\n}\n\nfunction getErrorCode(error: unknown): string | undefined {\n  if (!isObject(error)) return undefined;\n  const code = error.code ?? error.errno;\n  return typeof code === \"string\" ? code : undefined;\n}\n\nfunction getErrorStatus(error: unknown): number | undefined {\n  if (!isObject(error)) return undefined;\n  const direct = error.status ?? error.statusCode;\n  if (typeof direct === \"number\") return direct;\n  if (isObject(error.response) && typeof error.response.status === \"number\") {\n    return error.response.status;\n  }\n  return undefined;\n}\n\nfunction getErrorChildren(error: unknown): unknown[] {\n  if (!isObject(error)) return [];\n  const children: unknown[] = [];\n  if (\"cause\" in error) children.push(error.cause);\n  if (error instanceof AggregateError) children.push(...error.errors);\n  return children;\n}\n\nconst CONNECTIVITY_ERROR_CODES = new Set([\n  \"ECONNREFUSED\",\n  \"ECONNRESET\",\n  \"ENOTFOUND\",\n  \"ETIMEDOUT\",\n  \"EAI_AGAIN\",\n  \"EAI_NODATA\",\n  \"EAI_NONAME\",\n  \"EHOSTUNREACH\",\n  \"ENETUNREACH\",\n  \"CERT_HAS_EXPIRED\",\n  \"DEPTH_ZERO_SELF_SIGNED_CERT\",\n  \"ERR_TLS_CERT_ALTNAME_INVALID\",\n  \"SELF_SIGNED_CERT_IN_CHAIN\",\n  \"UNABLE_TO_VERIFY_LEAF_SIGNATURE\",\n]);\n\nfunction isConnectivityMessage(message: string): boolean {\n  return (\n    /\\bconnection (?:refused|reset|timed out)\\b/i.test(message) ||\n    /\\bsocket hang up\\b/i.test(message) ||\n    /\\bnetwork error\\b/i.test(message) ||\n    /\\bcan'?t connect to\\b/i.test(message) ||\n    /\\bcertificate has expired\\b/i.test(message) ||\n    /\\bunable to verify the first certificate\\b/i.test(message) ||\n    /\\bupstream connect error or disconnect\\/reset before headers\\b/i.test(\n      message,\n    )\n  );\n}\n\nfunction isConnectivityError(error: unknown): boolean {\n  const seen = new Set<unknown>();\n  const stack = [error];\n\n  while (stack.length > 0) {\n    const current = stack.pop();\n    if (current === undefined || seen.has(current)) continue;\n    seen.add(current);\n\n    const code = getErrorCode(current);\n    if (\n      code &&\n      (CONNECTIVITY_ERROR_CODES.has(code) || code.startsWith(\"UND_ERR_\"))\n    ) {\n      return true;\n    }\n\n    const status = getErrorStatus(current);\n    if (status === 502 || status === 503 || status === 504) return true;\n\n    if (isConnectivityMessage(getErrorMessage(current))) return true;\n\n    stack.push(...getErrorChildren(current));\n  }\n\n  return false;\n}\n\n/**\n * Extract parameters from a SQL query\n * @param sql - the SQL query to extract parameters from\n * @returns an array of parameter names\n */\nexport function extractParameters(\n  sql: string,\n  ranges?: Array<[number, number]>,\n): string[] {\n  const protectedRanges = ranges ?? getProtectedRanges(sql);\n  const matches = sql.matchAll(/(?<!:):([a-zA-Z_]\\w*)/g);\n  const params = new Set<string>();\n  for (const match of matches) {\n    if (!isInsideProtectedRange(match.index, protectedRanges)) {\n      params.add(match[1]);\n    }\n  }\n  return Array.from(params);\n}\n\n// parameters that are injected by the server\nexport const SERVER_INJECTED_PARAMS = [\"workspaceId\"];\n\n/**\n * Generates the TypeScript type literal for query parameters from SQL.\n * Shared by both the success and failure paths.\n */\nfunction formatParametersType(sql: string): string {\n  const params = extractParameters(sql).filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p),\n  );\n  const paramTypes = extractParameterTypes(sql);\n\n  return params.length > 0\n    ? `{\\n      ${params\n        .map((p) => {\n          const sqlType = paramTypes[p];\n          const markerType = sqlType\n            ? sqlTypeToMarker[sqlType]\n            : \"SQLTypeMarker\";\n          const helper = sqlType ? sqlTypeToHelper[sqlType] : \"sql.*()\";\n          return `/** ${sqlType || \"any\"} - use ${helper} */\\n      ${p}: ${markerType}`;\n        })\n        .join(\";\\n      \")};\\n    }`\n    : \"Record<string, never>\";\n}\n\nexport function convertToQueryType(\n  result: DatabricksStatementExecutionResponse,\n  sql: string,\n  queryName: string,\n): { type: string; hasResults: boolean } {\n  const dataRows = result.result?.data_array || [];\n  const columns = dataRows.map((row) => ({\n    name: row[0] || \"\",\n    type_name: row[1]?.toUpperCase() || \"STRING\",\n    comment: row[2] || undefined,\n  }));\n\n  const paramsType = formatParametersType(sql);\n\n  // generate result fields with JSDoc\n  const resultFields = columns.map((column) => {\n    const normalizedType = normalizeTypeName(column.type_name);\n    const mappedType = typeMap[normalizedType] || \"unknown\";\n    // validate column name is a valid identifier\n    const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name)\n      ? column.name\n      : `\"${column.name}\"`;\n\n    // generate comment for column\n    const comment = column.comment\n      ? `/** ${column.comment} */\\n      `\n      : `/** @sqlType ${column.type_name} */\\n      `;\n\n    return `${comment}${name}: ${mappedType}`;\n  });\n\n  const hasResults = resultFields.length > 0;\n\n  const type = `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: ${\n      hasResults\n        ? `Array<{\n      ${resultFields.join(\";\\n      \")};\n    }>`\n        : \"unknown\"\n    };\n  }`;\n\n  return { type, hasResults };\n}\n\n/**\n * Used when DESCRIBE QUERY fails so the query still appears in QueryRegistry.\n * Generates a type with unknown result from SQL alone (no warehouse call).\n */\nfunction generateUnknownResultQuery(sql: string, queryName: string): string {\n  const paramsType = formatParametersType(sql);\n\n  return `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: unknown;\n  }`;\n}\n\n/**\n * Degrade gracefully when DESCRIBE can't produce a fresh schema (transient\n * connectivity outage, or a warehouse that's reachable but not ready). Reuse\n * the last-good cached type when the SQL hash is unchanged, otherwise emit\n * `unknown` from SQL alone. Never persists `result: unknown`.\n */\nfunction degradedType(\n  cache: Awaited<ReturnType<typeof loadCache>>,\n  queryName: string,\n  sql: string,\n  sqlHash: string,\n): string {\n  const prior = cache.queries[queryName];\n  const canReusePrior = prior?.hash === sqlHash && !prior.retry;\n  return canReusePrior\n    ? prior.type\n    : generateUnknownResultQuery(sql, queryName);\n}\n\nexport function extractParameterTypes(sql: string): Record<string, string> {\n  const paramTypes: Record<string, string> = {};\n  // Alternation order matters: TIMESTAMP_NTZ must precede TIMESTAMP so the\n  // regex engine doesn't greedy-match TIMESTAMP and leave `_NTZ` unconsumed.\n  const regex =\n    /--\\s*@param\\s+(\\w+)\\s+(STRING|NUMERIC|DECIMAL|BIGINT|TINYINT|SMALLINT|INT|FLOAT|DOUBLE|BOOLEAN|DATE|TIMESTAMP_NTZ|TIMESTAMP|BINARY)\\b/gi;\n  const matches = sql.matchAll(regex);\n  for (const match of matches) {\n    const [, paramName, paramType] = match;\n    paramTypes[paramName] = paramType.toUpperCase();\n  }\n\n  return paramTypes;\n}\n\nexport function defaultForType(sqlType: string | undefined): string {\n  switch (sqlType?.toUpperCase()) {\n    case \"NUMERIC\":\n    case \"DECIMAL\":\n    case \"BIGINT\":\n    case \"TINYINT\":\n    case \"SMALLINT\":\n    case \"INT\":\n      return \"0\";\n    case \"FLOAT\":\n    case \"DOUBLE\":\n      return \"0.0\";\n    case \"STRING\":\n      return \"''\";\n    case \"BOOLEAN\":\n      return \"true\";\n    case \"DATE\":\n      return \"'2000-01-01'\";\n    case \"TIMESTAMP\":\n      return \"'2000-01-01T00:00:00Z'\";\n    case \"TIMESTAMP_NTZ\":\n      return \"'2000-01-01T00:00:00'\";\n    case \"BINARY\":\n      return \"X'00'\";\n    default:\n      return \"''\";\n  }\n}\n\n/**\n * Infer parameter types from positional context in SQL.\n * V1 only infers NUMERIC from patterns like LIMIT, OFFSET, TOP,\n * FETCH FIRST ... ROWS, and arithmetic operators.\n * Parameters inside string literals or SQL comments are ignored.\n */\nexport function inferParameterTypes(\n  sql: string,\n  ranges?: Array<[number, number]>,\n): Record<string, string> {\n  const inferred: Record<string, string> = {};\n  const protectedRanges = ranges ?? getProtectedRanges(sql);\n\n  for (const pattern of NUMERIC_PATTERNS) {\n    for (const match of sql.matchAll(pattern)) {\n      if (!isInsideProtectedRange(match.index, protectedRanges)) {\n        inferred[match[1]] = \"NUMERIC\";\n      }\n    }\n  }\n\n  return inferred;\n}\n\n/**\n * Generate query schemas from a folder of SQL files\n * It uses DESCRIBE QUERY to get the schema without executing the query\n * @param queryFolder - the folder containing the SQL files\n * @param warehouseId - the warehouse id to use for schema analysis\n * @param options - options for the query generation\n * @param options.noCache - if true, skip the cache and regenerate all types\n * @param options.mode - preflight policy: \"non-blocking\" never probes the\n *   warehouse and never describes (emits cached/`unknown` types and returns\n *   immediately), \"blocking\" waits for a starting warehouse and starts (then\n *   waits for) a stopped one, treating only a deleted/deleting warehouse as\n *   fatal. Defaults to \"non-blocking\".\n * @returns an array of query schemas\n */\nexport async function generateQueriesFromDescribe(\n  queryFolder: string,\n  warehouseId: string,\n  options: {\n    noCache?: boolean;\n    concurrency?: number;\n    mode?: PreflightMode;\n  } = {},\n): Promise<QueryGenerationResult> {\n  const {\n    noCache = false,\n    concurrency: rawConcurrency = 10,\n    mode = \"non-blocking\",\n  } = options;\n  const concurrency =\n    typeof rawConcurrency === \"number\" && Number.isFinite(rawConcurrency)\n      ? Math.max(1, Math.floor(rawConcurrency))\n      : 10;\n\n  // read all query files and cache in parallel\n  const [allFiles, cache] = await Promise.all([\n    fs.readdir(queryFolder),\n    noCache\n      ? ({ version: CACHE_VERSION, queries: {} } as Awaited<\n          ReturnType<typeof loadCache>\n        >)\n      : loadCache(),\n  ]);\n\n  const queryFiles = allFiles.filter((file) => file.endsWith(\".sql\"));\n  logger.debug(\"Found %d SQL queries\", queryFiles.length);\n\n  const client = new WorkspaceClient({});\n  const spinner = new Spinner();\n\n  // Read all SQL files in parallel\n  const sqlContents = await Promise.all(\n    queryFiles.map((file) => fs.readFile(path.join(queryFolder, file), \"utf8\")),\n  );\n\n  const startTime = performance.now();\n\n  // Phase 1: Check cache, separate cached vs uncached\n  const cachedResults: Array<{ index: number; schema: QuerySchema }> = [];\n  const uncachedQueries: Array<{\n    index: number;\n    queryName: string;\n    sql: string;\n    sqlHash: string;\n    cleanedSql: string;\n  }> = [];\n  const logEntries: Array<{\n    queryName: string;\n    status: \"HIT\" | \"MISS\";\n    // Absent for clean hits/misses. \"syntax\" = bad SQL on a reachable warehouse;\n    // \"connectivity\" = warehouse unreachable; \"empty\" = described but no columns;\n    // \"fatal\" = non-SQL setup/request failure surfaced after .d.ts emission.\n    kind?: \"syntax\" | \"connectivity\" | \"empty\" | \"fatal\";\n    error?: { code?: string; message: string };\n  }> = [];\n\n  for (let i = 0; i < queryFiles.length; i++) {\n    const file = queryFiles[i];\n    const rawName = path.basename(file, \".sql\");\n    const queryName = normalizeQueryName(rawName);\n\n    const sql = sqlContents[i];\n    const sqlHash = hashSQL(sql);\n\n    const cached = cache.queries[queryName];\n    if (cached && cached.hash === sqlHash && !cached.retry) {\n      cachedResults.push({\n        index: i,\n        schema: { name: queryName, type: cached.type },\n      });\n      logEntries.push({ queryName, status: \"HIT\" });\n    } else {\n      const protectedRanges = getProtectedRanges(sql);\n      const annotatedTypes = extractParameterTypes(sql);\n      const inferredTypes = inferParameterTypes(sql, protectedRanges);\n      const parameterTypes = { ...inferredTypes, ...annotatedTypes };\n      const sqlWithDefaults = sql.replace(\n        /(?<!:):([a-zA-Z_]\\w*)/g,\n        (original, paramName, offset) => {\n          if (isInsideProtectedRange(offset, protectedRanges)) {\n            return original;\n          }\n          return defaultForType(parameterTypes[paramName]);\n        },\n      );\n\n      // Warn about unresolved parameters\n      const allParams = extractParameters(sql, protectedRanges);\n      for (const param of allParams) {\n        if (SERVER_INJECTED_PARAMS.includes(param)) continue;\n        if (parameterTypes[param]) continue;\n        logger.warn(\n          '%s: parameter \":%s\" has no type annotation or inference. Add %s to the query file.',\n          queryFiles[i],\n          param,\n          `-- @param ${param} <TYPE>`,\n        );\n      }\n\n      const cleanedSql = sqlWithDefaults.trim().replace(/;\\s*$/, \"\");\n      uncachedQueries.push({ index: i, queryName, sql, sqlHash, cleanedSql });\n    }\n  }\n\n  // Phase 2: Execute all uncached DESCRIBE calls in parallel\n  type DescribeResult =\n    | {\n        // Described successfully with a result schema — the only case we cache.\n        status: \"ok\";\n        index: number;\n        schema: QuerySchema;\n        cacheEntry: { hash: string; type: string; retry: boolean };\n      }\n    | {\n        // Reachable warehouse ran DESCRIBE and rejected the statement — a\n        // genuine SQL error. Eligible to fail the build; never cached.\n        status: \"syntax\";\n        index: number;\n        schema: QuerySchema;\n        error: { code?: string; message: string };\n      }\n    | {\n        // DESCRIBE succeeded but returned no columns — soft `unknown`. Not a\n        // failure, not cached, retried next run.\n        status: \"empty\";\n        index: number;\n        schema: QuerySchema;\n      }\n    | {\n        // Warehouse reachable but returned a non-terminal state (PENDING/\n        // RUNNING) with no rows — stopped/cold-starting/busy. Degrade like a\n        // transient outage (reuse cache or `unknown`); not cached, not empty.\n        status: \"unavailable\";\n        index: number;\n        schema: QuerySchema;\n      };\n\n  const freshResults: Array<{ index: number; schema: QuerySchema }> = [];\n  // Genuine SQL errors (reachable warehouse). Connectivity failures are NOT\n  // recorded here — they degrade silently so a transient outage isn't fatal.\n  const syntaxErrors: QuerySyntaxError[] = [];\n  const fatalErrors: QueryFatalError[] = [];\n\n  if (uncachedQueries.length > 0) {\n    // One-time warehouse preflight (before issuing any DESCRIBE). A single\n    // warehouses.get classifies the warehouse so we can skip the whole describe\n    // batch when it can't serve this run, instead of letting every query fail\n    // (and re-fail next run). Reuses this file's degrade/classify helpers so a\n    // not-ready warehouse degrades exactly like a per-query outage.\n    let decision: ReturnType<typeof decidePreflight> = \"proceed\";\n    let fatalMessage = \"\";\n    if (mode === \"non-blocking\") {\n      // `non-blocking` never describes and must make ZERO warehouse round-trips:\n      // skip the probe entirely (no getWarehouseState) and go straight to\n      // degradeAll. A foreground/one-shot run can't describe in the background,\n      // so it emits best-available types (reused cache or `unknown`) and returns\n      // now.\n      decision = \"degradeAll\";\n    } else {\n      try {\n        const state = await getWarehouseState(client, warehouseId);\n        decision = decidePreflight(state, mode);\n        if (decision === \"fatal\") {\n          fatalMessage = `warehouse ${warehouseId} is ${state}`;\n        }\n        if (decision === \"startWaitProceed\") {\n          // Stopped/stopping warehouse: nudge it out of the stopped state, then\n          // poll to RUNNING. treatStoppedAsTransient rides out the stale\n          // pre-start STOPPED/STOPPING reading the start hasn't propagated past\n          // yet — only DELETED/DELETING (or the deadline) ends the wait early.\n          await startWarehouse(client, warehouseId);\n          const final = await waitUntilRunning(client, warehouseId, {\n            maxMs: PREFLIGHT_WAIT_MAX_MS,\n            treatStoppedAsTransient: true,\n          });\n          if (final === \"RUNNING\") {\n            decision = \"proceed\";\n          } else {\n            decision = \"fatal\";\n            fatalMessage = `warehouse ${warehouseId} did not reach RUNNING (now ${final})`;\n          }\n        }\n        if (decision === \"waitThenProceed\") {\n          const final = await waitUntilRunning(client, warehouseId, {\n            maxMs: PREFLIGHT_WAIT_MAX_MS,\n          });\n          if (final === \"RUNNING\") {\n            decision = \"proceed\";\n          } else {\n            decision = \"fatal\";\n            fatalMessage = `warehouse ${warehouseId} did not reach RUNNING (now ${final})`;\n          }\n        }\n      } catch (err) {\n        if (isConnectivityError(err)) {\n          // Warehouse unreachable (transient outage): degrade silently like a\n          // per-query connectivity failure — never fail a build on a blip.\n          decision = \"degradeAll\";\n        } else {\n          // Auth, bad warehouse id, malformed config, or a timed-out wait: fatal.\n          decision = \"fatal\";\n          fatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;\n        }\n      }\n    }\n\n    if (decision !== \"proceed\") {\n      // degradeAll or fatal: skip DESCRIBE entirely. Every uncached query gets a\n      // degraded schema (reused cache or `unknown`); fatal additionally records\n      // a fatalError per query so the caller fails the build after writing.\n      const kind = decision === \"fatal\" ? \"fatal\" : \"connectivity\";\n      for (const { index, queryName, sql, sqlHash } of uncachedQueries) {\n        freshResults.push({\n          index,\n          schema: {\n            name: queryName,\n            type: degradedType(cache, queryName, sql, sqlHash),\n          },\n        });\n        if (decision === \"fatal\") {\n          fatalErrors.push({ name: queryName, message: fatalMessage });\n          logEntries.push({\n            queryName,\n            status: \"MISS\",\n            kind,\n            error: { message: fatalMessage },\n          });\n        } else {\n          logEntries.push({ queryName, status: \"MISS\", kind });\n        }\n      }\n    } else {\n      let completed = 0;\n      const total = uncachedQueries.length;\n      spinner.start(\n        `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (0/${total})`,\n      );\n\n      const describeOne = async ({\n        index,\n        queryName,\n        sql,\n        sqlHash,\n        cleanedSql,\n      }: (typeof uncachedQueries)[number]): Promise<DescribeResult> => {\n        const result = (await client.statementExecution.executeStatement({\n          statement: `DESCRIBE QUERY ${cleanedSql}`,\n          warehouse_id: warehouseId,\n        })) as DatabricksStatementExecutionResponse;\n\n        completed++;\n        spinner.update(\n          `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (${completed}/${total})`,\n        );\n\n        logger.debug(\n          \"DESCRIBE result for %s: state=%s, rows=%d\",\n          queryName,\n          result.status.state,\n          result.result?.data_array?.length ?? 0,\n        );\n\n        if (result.status.state === \"FAILED\") {\n          // The warehouse was reachable and ran DESCRIBE, but the statement\n          // failed — a genuine SQL error (bad table, syntax, incompatible type).\n          const sqlError =\n            result.status.error?.message || \"Query execution failed\";\n          // The failure is surfaced once, formatted, by the aggregated\n          // TypegenSyntaxError (and the summary table) — don't also log the raw\n          // message here or every SQL error prints twice in dev.\n          const type = generateUnknownResultQuery(sql, queryName);\n          return {\n            status: \"syntax\",\n            index,\n            schema: { name: queryName, type },\n            error: parseError(sqlError),\n          };\n        }\n\n        if (result.status.state !== \"SUCCEEDED\") {\n          // Non-terminal state (PENDING/RUNNING) with no result rows: the\n          // warehouse is reachable but not ready (stopped, cold-starting, or\n          // busy). Degrade like a transient outage — reuse the last-good cached\n          // type when the SQL is unchanged, else emit `unknown`. Never \"empty\":\n          // treating this as empty would emit `result: unknown` AND discard the\n          // good cached type, silently throwing away working types.\n          return {\n            status: \"unavailable\",\n            index,\n            schema: {\n              name: queryName,\n              type: degradedType(cache, queryName, sql, sqlHash),\n            },\n          };\n        }\n\n        const { type, hasResults } = convertToQueryType(result, sql, queryName);\n        if (!hasResults) {\n          // Described, but no result columns. Emit `unknown` and retry next run;\n          // do not cache (we never persist `result: unknown`).\n          return { status: \"empty\", index, schema: { name: queryName, type } };\n        }\n        return {\n          status: \"ok\",\n          index,\n          schema: { name: queryName, type },\n          cacheEntry: { hash: sqlHash, type, retry: false },\n        };\n      };\n\n      // Process in chunks, saving cache after each chunk\n      const processBatchResults = (\n        settled: PromiseSettledResult<DescribeResult>[],\n        batchOffset: number,\n      ) => {\n        for (let i = 0; i < settled.length; i++) {\n          const entry = settled[i];\n          const { queryName } = uncachedQueries[batchOffset + i];\n\n          if (entry.status === \"fulfilled\") {\n            const res = entry.value;\n            freshResults.push({ index: res.index, schema: res.schema });\n\n            if (res.status === \"ok\") {\n              // Only a successful describe with a result schema is cached.\n              cache.queries[queryName] = res.cacheEntry;\n              logEntries.push({ queryName, status: \"MISS\" });\n            } else if (res.status === \"syntax\") {\n              // Genuine SQL error — record it for the caller's prod/dev gate.\n              // Not cached: re-described next run so a fixed query recovers.\n              syntaxErrors.push({\n                name: queryName,\n                message: res.error.message,\n              });\n              logEntries.push({\n                queryName,\n                status: \"MISS\",\n                kind: \"syntax\",\n                error: res.error,\n              });\n            } else if (res.status === \"empty\") {\n              // status === \"empty\": described, no columns. Soft unknown, not cached.\n              logEntries.push({ queryName, status: \"MISS\", kind: \"empty\" });\n            } else {\n              // status === \"unavailable\": non-terminal DESCRIBE (warehouse\n              // stopped/cold-starting/busy). Degrade like a transient outage:\n              // tag OFFLINE, count as degraded, never cache.\n              logEntries.push({\n                queryName,\n                status: \"MISS\",\n                kind: \"connectivity\",\n              });\n            }\n          } else {\n            // executeStatement rejected without a normal StatementExecution result.\n            // Only structured transport/connectivity failures are treated as\n            // offline; auth, bad warehouse IDs, malformed requests, and SDK/config\n            // failures stay fatal so users fix the underlying setup issue.\n            completed++;\n            spinner.update(\n              `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (${completed}/${total})`,\n            );\n\n            const { sql, sqlHash, index } = uncachedQueries[batchOffset + i];\n            const reason = getErrorDiagnostic(entry.reason);\n            const error = parseError(reason);\n            const priorEntry = cache.queries[queryName];\n            const canReusePrior =\n              priorEntry?.hash === sqlHash && !priorEntry.retry;\n            const type = degradedType(cache, queryName, sql, sqlHash);\n            freshResults.push({ index, schema: { name: queryName, type } });\n\n            if (!isConnectivityError(entry.reason)) {\n              fatalErrors.push({ name: queryName, message: error.message });\n              logEntries.push({\n                queryName,\n                status: \"MISS\",\n                kind: \"fatal\",\n                error,\n              });\n              continue;\n            }\n\n            logger.warn(\n              \"DESCRIBE unreachable for %s: %s — %s\",\n              queryName,\n              reason,\n              canReusePrior\n                ? \"reusing last cached type\"\n                : \"emitting unknown (no matching cache)\",\n            );\n            logEntries.push({\n              queryName,\n              status: \"MISS\",\n              kind: \"connectivity\",\n              error,\n            });\n          }\n        }\n      };\n\n      if (uncachedQueries.length > concurrency) {\n        for (let b = 0; b < uncachedQueries.length; b += concurrency) {\n          const batch = uncachedQueries.slice(b, b + concurrency);\n          const batchResults = await Promise.allSettled(batch.map(describeOne));\n          processBatchResults(batchResults, b);\n          await saveCache(cache);\n        }\n      } else {\n        const settled = await Promise.allSettled(\n          uncachedQueries.map(describeOne),\n        );\n        processBatchResults(settled, 0);\n        await saveCache(cache);\n      }\n\n      spinner.stop(\"\");\n    }\n  }\n\n  const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);\n\n  // Print formatted table\n  if (logEntries.length > 0) {\n    const maxNameLen = Math.max(...logEntries.map((e) => e.queryName.length));\n    const separator = pc.dim(\"─\".repeat(50));\n    console.log(\"\");\n    console.log(\n      `  ${pc.bold(\"Typegen Queries\")} ${pc.dim(`(${logEntries.length})`)}`,\n    );\n    console.log(`  ${separator}`);\n    for (const entry of logEntries) {\n      let tag: string;\n      switch (entry.kind) {\n        case \"syntax\":\n          tag = pc.bold(pc.red(\"SQL ERR\"));\n          break;\n        case \"connectivity\":\n          tag = pc.bold(pc.yellow(\"OFFLINE\"));\n          break;\n        case \"empty\":\n          tag = pc.dim(\"EMPTY  \");\n          break;\n        case \"fatal\":\n          tag = pc.bold(pc.red(\"FATAL \"));\n          break;\n        default:\n          tag =\n            entry.status === \"HIT\"\n              ? `cache ${pc.bold(pc.green(\"HIT  \"))}`\n              : `cache ${pc.bold(pc.yellow(\"MISS \"))}`;\n      }\n      const rawName = entry.queryName.padEnd(maxNameLen);\n      // Only genuine SQL errors are struck through. Connectivity/empty kept a\n      // usable type (reused or unknown), so they read as degraded, not broken.\n      const name =\n        entry.kind === \"syntax\" || entry.kind === \"fatal\"\n          ? pc.dim(pc.strikethrough(rawName))\n          : rawName;\n      const errorCode = entry.error?.message.match(/\\[([^\\]]+)\\]/)?.[1];\n      const reason = errorCode ? `  ${pc.dim(errorCode)}` : \"\";\n      console.log(`  ${tag}  ${name}${reason}`);\n    }\n    const newCount = logEntries.filter(\n      (e) => e.status === \"MISS\" && !e.kind,\n    ).length;\n    const cacheCount = logEntries.filter((e) => e.status === \"HIT\").length;\n    const syntaxCount = logEntries.filter((e) => e.kind === \"syntax\").length;\n    const offlineCount = logEntries.filter(\n      (e) => e.kind === \"connectivity\",\n    ).length;\n    const emptyCount = logEntries.filter((e) => e.kind === \"empty\").length;\n    const fatalCount = logEntries.filter((e) => e.kind === \"fatal\").length;\n    console.log(`  ${separator}`);\n    const parts = [`${newCount} new`, `${cacheCount} from cache`];\n    if (syntaxCount > 0)\n      parts.push(\n        `${syntaxCount} SQL ${syntaxCount === 1 ? \"error\" : \"errors\"}`,\n      );\n    if (offlineCount > 0) parts.push(`${offlineCount} degraded`);\n    if (emptyCount > 0) parts.push(`${emptyCount} empty`);\n    if (fatalCount > 0)\n      parts.push(\n        `${fatalCount} fatal ${fatalCount === 1 ? \"error\" : \"errors\"}`,\n      );\n    console.log(`  ${parts.join(\", \")}. ${pc.dim(`${elapsed}s`)}`);\n    console.log(\"\");\n  }\n\n  // Merge and sort by original file index for deterministic output\n  const schemas = [...cachedResults, ...freshResults]\n    .sort((a, b) => a.index - b.index)\n    .map((r) => r.schema);\n\n  return { schemas, syntaxErrors, fatalErrors };\n}\n\n/**\n * Normalize query name by removing the .obo extension\n * @param queryName - the query name to normalize\n * @returns the normalized query name\n */\nfunction normalizeQueryName(fileName: string): string {\n  return fileName.replace(/\\.obo$/, \"\");\n}\n\n/**\n * Normalize SQL type name by removing parameters/generics\n * Examples:\n *   DECIMAL(38,6) -> DECIMAL\n *   ARRAY<STRING> -> ARRAY\n *   MAP<STRING,INT> -> MAP\n *   STRUCT<name:STRING> -> STRUCT\n *   INTERVAL DAY TO SECOND -> INTERVAL\n *   GEOGRAPHY(4326) -> GEOGRAPHY\n */\nexport function normalizeTypeName(typeName: string): string {\n  return typeName\n    .replace(/\\(.*\\)$/, \"\") // remove (p, s) eg: DECIMAL(38,6) -> DECIMAL\n    .replace(/<.*>$/, \"\") // remove <T> eg: ARRAY<STRING> -> ARRAY\n    .split(\" \")[0]; // take first word eg: INTERVAL DAY TO SECOND -> INTERVAL\n}\n\n/** Type Map for Databricks data types to JavaScript types */\nconst typeMap: Record<string, string> = {\n  // string types\n  STRING: \"string\",\n  BINARY: \"string\",\n  // boolean\n  BOOLEAN: \"boolean\",\n  // numeric types\n  TINYINT: \"number\",\n  SMALLINT: \"number\",\n  INT: \"number\",\n  BIGINT: \"number\",\n  FLOAT: \"number\",\n  DOUBLE: \"number\",\n  DECIMAL: \"number\",\n  // date/time types\n  DATE: \"string\",\n  TIMESTAMP: \"string\",\n  TIMESTAMP_NTZ: \"string\",\n  INTERVAL: \"string\",\n  // complex types\n  ARRAY: \"unknown[]\",\n  MAP: \"Record<string, unknown>\",\n  STRUCT: \"Record<string, unknown>\",\n  OBJECT: \"Record<string, unknown>\",\n  VARIANT: \"unknown\",\n  // spatial types\n  GEOGRAPHY: \"unknown\",\n  GEOMETRY: \"unknown\",\n  // null type\n  VOID: \"null\",\n};\n"],"mappings":"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"}
+{"version":3,"file":"query-registry.js","names":[],"sources":["../../src/type-generator/query-registry.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport pc from \"picocolors\";\nimport { createLogger } from \"../logging/logger\";\nimport { CACHE_VERSION, hashSQL, loadCache, saveCache } from \"./cache\";\nimport { getErrorDiagnostic, isConnectivityError } from \"./errors\";\nimport { decidePreflight, type PreflightMode } from \"./preflight\";\nimport { Spinner } from \"./spinner\";\nimport { type DescribeFormatMemo, describeAdaptive } from \"./statement-result\";\nimport {\n  type DatabricksStatementExecutionResponse,\n  type QueryFatalError,\n  type QueryGenerationResult,\n  type QuerySchema,\n  type QuerySyntaxError,\n  sqlTypeToHelper,\n  sqlTypeToMarker,\n} from \"./types\";\nimport {\n  getWarehouseState,\n  startWarehouse,\n  waitUntilRunning,\n} from \"./warehouse-status\";\n\nconst logger = createLogger(\"type-generator:query-registry\");\n\n/**\n * Upper bound on how long a `blocking`-mode preflight will wait for a starting\n * warehouse to reach RUNNING before giving up (~5 min). Generous enough to ride\n * out a cold start without hanging an interactive CLI invocation indefinitely.\n */\nconst PREFLIGHT_WAIT_MAX_MS = 300_000;\n\n/**\n * Regex breakdown:\n *   '(?:[^']|'')*'   — matches a SQL string literal, including escaped '' pairs\n *   |                 — alternation: whichever branch matches first at a position wins\n *   --[^\\n]*          — matches a single-line SQL comment\n *\n * Because the regex engine scans left-to-right, a `'` is consumed as a string\n * literal before any `--` inside it could match as a comment — giving us\n * correct single-pass ordering without a manual state machine.\n *\n * V1: no block-comment support (deferred to next PR).\n */\nconst PROTECTED_RANGE_RE = /'(?:[^']|'')*'|--[^\\n]*/g;\n\n/**\n * Numeric-context patterns for positional type inference.\n * Hoisted to module scope — safe because matchAll() clones the regex internally.\n */\nconst NUMERIC_PATTERNS: RegExp[] = [\n  /\\bLIMIT\\s+:([a-zA-Z_]\\w*)/gi,\n  /\\bOFFSET\\s+:([a-zA-Z_]\\w*)/gi,\n  /\\bTOP\\s+:([a-zA-Z_]\\w*)/gi,\n  /\\bFETCH\\s+FIRST\\s+:([a-zA-Z_]\\w*)\\s+ROWS/gi,\n  // V1 limitation: arithmetic operators may false-positive for date\n  // expressions like `:start_date - INTERVAL '1 day'`. A smarter\n  // heuristic (e.g. look-ahead for INTERVAL) is deferred to a future PR.\n  /[+\\-*/]\\s*:([a-zA-Z_]\\w*)/g,\n  /:([a-zA-Z_]\\w*)\\s*[+\\-*/]/g,\n];\n\nexport function getProtectedRanges(sql: string): Array<[number, number]> {\n  const ranges: Array<[number, number]> = [];\n  for (const m of sql.matchAll(PROTECTED_RANGE_RE)) {\n    ranges.push([m.index, m.index + m[0].length]);\n  }\n  return ranges;\n}\n\nfunction isInsideProtectedRange(\n  offset: number,\n  ranges: Array<[number, number]>,\n): boolean {\n  return ranges.some(([start, end]) => offset >= start && offset < end);\n}\n\n/**\n * Parse a raw API/SDK error into a structured code + message.\n * Handles Databricks-style JSON bodies embedded in the message string,\n * e.g. `Response from server (Bad Request) {\"error_code\":\"...\",\"message\":\"...\"}`.\n */\nfunction parseError(raw: string): { code?: string; message: string } {\n  const jsonMatch = raw.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    try {\n      const parsed = JSON.parse(jsonMatch[0]);\n      if (parsed.error_code || parsed.message) {\n        return {\n          code: parsed.error_code,\n          message: parsed.message || raw,\n        };\n      }\n    } catch {\n      // not valid JSON, fall through\n    }\n  }\n  return { message: raw };\n}\n\n/**\n * Extract parameters from a SQL query\n * @param sql - the SQL query to extract parameters from\n * @returns an array of parameter names\n */\nexport function extractParameters(\n  sql: string,\n  ranges?: Array<[number, number]>,\n): string[] {\n  const protectedRanges = ranges ?? getProtectedRanges(sql);\n  const matches = sql.matchAll(/(?<!:):([a-zA-Z_]\\w*)/g);\n  const params = new Set<string>();\n  for (const match of matches) {\n    if (!isInsideProtectedRange(match.index, protectedRanges)) {\n      params.add(match[1]);\n    }\n  }\n  return Array.from(params);\n}\n\n// parameters that are injected by the server\nexport const SERVER_INJECTED_PARAMS = [\"workspaceId\"];\n\n/**\n * Generates the TypeScript type literal for query parameters from SQL.\n * Shared by both the success and failure paths.\n */\nfunction formatParametersType(sql: string): string {\n  const params = extractParameters(sql).filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p),\n  );\n  const paramTypes = extractParameterTypes(sql);\n\n  return params.length > 0\n    ? `{\\n      ${params\n        .map((p) => {\n          const sqlType = paramTypes[p];\n          const markerType = sqlType\n            ? sqlTypeToMarker[sqlType]\n            : \"SQLTypeMarker\";\n          const helper = sqlType ? sqlTypeToHelper[sqlType] : \"sql.*()\";\n          return `/** ${sqlType || \"any\"} - use ${helper} */\\n      ${p}: ${markerType}`;\n        })\n        .join(\";\\n      \")};\\n    }`\n    : \"Record<string, never>\";\n}\n\nexport function convertToQueryType(\n  result: DatabricksStatementExecutionResponse,\n  sql: string,\n  queryName: string,\n): { type: string; hasResults: boolean } {\n  const dataRows = result.result?.data_array || [];\n  const columns = dataRows.map((row) => ({\n    name: row[0] || \"\",\n    type_name: row[1]?.toUpperCase() || \"STRING\",\n    comment: row[2] || undefined,\n  }));\n\n  const paramsType = formatParametersType(sql);\n\n  // generate result fields with JSDoc\n  const resultFields = columns.map((column) => {\n    const normalizedType = normalizeTypeName(column.type_name);\n    const mappedType = typeMap[normalizedType] || \"unknown\";\n    // validate column name is a valid identifier\n    const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name)\n      ? column.name\n      : `\"${column.name}\"`;\n\n    // generate comment for column\n    const comment = column.comment\n      ? `/** ${column.comment.replace(/\\*\\//g, \"* /\")} */\\n      `\n      : `/** @sqlType ${column.type_name.replace(/\\*\\//g, \"* /\")} */\\n      `;\n\n    return `${comment}${name}: ${mappedType}`;\n  });\n\n  const hasResults = resultFields.length > 0;\n\n  const type = `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: ${\n      hasResults\n        ? `Array<{\n      ${resultFields.join(\";\\n      \")};\n    }>`\n        : \"unknown\"\n    };\n  }`;\n\n  return { type, hasResults };\n}\n\n/**\n * Used when DESCRIBE QUERY fails so the query still appears in QueryRegistry.\n * Generates a type with unknown result from SQL alone (no warehouse call).\n */\nfunction generateUnknownResultQuery(sql: string, queryName: string): string {\n  const paramsType = formatParametersType(sql);\n\n  return `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: unknown;\n  }`;\n}\n\n/**\n * Degrade gracefully when DESCRIBE can't produce a fresh schema (transient\n * connectivity outage, or a warehouse that's reachable but not ready). Reuse\n * the last-good cached type when the SQL hash is unchanged, otherwise emit\n * `unknown` from SQL alone. Never persists `result: unknown`.\n */\nfunction degradedType(\n  cache: Awaited<ReturnType<typeof loadCache>>,\n  queryName: string,\n  sql: string,\n  sqlHash: string,\n): string {\n  const prior = cache.queries[queryName];\n  const canReusePrior = prior?.hash === sqlHash && !prior.retry;\n  return canReusePrior\n    ? prior.type\n    : generateUnknownResultQuery(sql, queryName);\n}\n\n// Single source of truth for the `@param` type alternation, shared by\n// extractParameterTypes and extractParameterDefaults so the two can't drift.\n// Alternation order matters: TIMESTAMP_NTZ must precede TIMESTAMP so the regex\n// engine doesn't greedy-match TIMESTAMP and leave `_NTZ` unconsumed.\nconst PARAM_TYPE_ALTERNATION =\n  \"STRING|NUMERIC|DECIMAL|BIGINT|TINYINT|SMALLINT|INT|FLOAT|DOUBLE|BOOLEAN|DATE|TIMESTAMP_NTZ|TIMESTAMP|BINARY\";\n\nexport function extractParameterTypes(sql: string): Record<string, string> {\n  const paramTypes: Record<string, string> = {};\n  const regex = new RegExp(\n    `--\\\\s*@param\\\\s+(\\\\w+)\\\\s+(${PARAM_TYPE_ALTERNATION})\\\\b`,\n    \"gi\",\n  );\n  const matches = sql.matchAll(regex);\n  for (const match of matches) {\n    const [, paramName, paramType] = match;\n    paramTypes[paramName] = paramType.toUpperCase();\n  }\n\n  return paramTypes;\n}\n\nexport function defaultForType(sqlType: string | undefined): string {\n  switch (sqlType?.toUpperCase()) {\n    case \"NUMERIC\":\n    case \"DECIMAL\":\n    case \"BIGINT\":\n    case \"TINYINT\":\n    case \"SMALLINT\":\n    case \"INT\":\n      return \"0\";\n    case \"FLOAT\":\n    case \"DOUBLE\":\n      return \"0.0\";\n    case \"STRING\":\n      return \"''\";\n    case \"BOOLEAN\":\n      return \"true\";\n    case \"DATE\":\n      return \"'2000-01-01'\";\n    case \"TIMESTAMP\":\n      return \"'2000-01-01T00:00:00Z'\";\n    case \"TIMESTAMP_NTZ\":\n      return \"'2000-01-01T00:00:00'\";\n    case \"BINARY\":\n      return \"X'00'\";\n    default:\n      return \"''\";\n  }\n}\n\n/**\n * True when `raw` is already a single, well-formed SQL single-quoted string\n * literal — i.e. it opens and closes with `'` and every interior quote is part\n * of an escaped `''` pair. `'2024-01-01'` and `'O''Brien'` qualify;\n * `'a' OR 1=1 OR 'b'` does not (it has lone interior quotes), so it is treated\n * as raw content and re-escaped rather than trusted. A backslash also\n * disqualifies it: Databricks/Spark treats `\\` as an escape inside literals (so\n * `'a\\'` is unterminated), and we never trust such input — it is re-escaped.\n */\nfunction isWellFormedStringLiteral(raw: string): boolean {\n  if (raw.length < 2 || !raw.startsWith(\"'\") || !raw.endsWith(\"'\")) {\n    return false;\n  }\n  const inner = raw.slice(1, -1);\n  if (inner.includes(\"\\\\\")) return false;\n  return !inner.replace(/''/g, \"\").includes(\"'\");\n}\n\n/**\n * Format a user-supplied sample value as a SQL literal for substitution into\n * the build-time DESCRIBE statement. Returns `null` when the value isn't valid\n * for its type, so the caller falls back to the safe type-based placeholder\n * instead of substituting attacker-controllable text.\n *\n * The value comes from a `.sql` file that may be shared via a template or\n * dependency, so it must not be able to inject SQL into `DESCRIBE QUERY`:\n * - string-like types are always emitted as one well-formed, fully-escaped\n *   single-quoted literal (a pre-quoted literal is kept as-is, anything else is\n *   quoted with both `\\` and `'` doubled so neither can terminate the literal),\n *   so the value can never break out of the string;\n * - numeric / boolean / binary values must match a strict literal shape and are\n *   rejected (`null`) otherwise, rather than being passed through verbatim.\n */\nfunction formatSampleValue(\n  sqlType: string | undefined,\n  raw: string,\n): string | null {\n  switch (sqlType?.toUpperCase()) {\n    case \"STRING\":\n    case \"DATE\":\n    case \"TIMESTAMP\":\n    case \"TIMESTAMP_NTZ\":\n      return isWellFormedStringLiteral(raw)\n        ? raw\n        : `'${raw.replace(/\\\\/g, \"\\\\\\\\\").replace(/'/g, \"''\")}'`;\n    case \"NUMERIC\":\n    case \"DECIMAL\":\n    case \"BIGINT\":\n    case \"TINYINT\":\n    case \"SMALLINT\":\n    case \"INT\":\n    case \"FLOAT\":\n    case \"DOUBLE\":\n      return /^[+-]?\\d+(\\.\\d+)?$/.test(raw) ? raw : null;\n    case \"BOOLEAN\":\n      return /^(?:true|false)$/i.test(raw) ? raw.toLowerCase() : null;\n    case \"BINARY\":\n      return /^X'[0-9a-fA-F]*'$/i.test(raw) ? raw : null;\n    default:\n      return null;\n  }\n}\n\n/**\n * Parse optional describe-time sample values from `@param` annotations, e.g.\n * `-- @param target_catalog STRING = main`. The value is substituted into the\n * SQL **only during DESCRIBE QUERY** so type generation can resolve queries\n * whose shape depends on a parameter value — most notably dynamic table names\n * via `IDENTIFIER(:target_catalog || '.schema.table')`, where the empty-string\n * default would otherwise produce malformed SQL. Runtime binding is unaffected:\n * the analytics plugin still binds the real parameter at execution time, so the\n * query stays portable across environments.\n *\n * Returns a map of parameter name to the formatted SQL literal to substitute.\n */\nexport function extractParameterDefaults(sql: string): Record<string, string> {\n  const defaults: Record<string, string> = {};\n  // Reuses PARAM_TYPE_ALTERNATION, then requires `= <value>` on the same line.\n  // All inter-token whitespace is horizontal-only (`[^\\S\\r\\n]`, not `\\s`): `\\s`\n  // matches newlines, so a value-less line like `-- @param x STRING =` would let\n  // `\\s*=\\s*(.+?)` swallow the *next* line as the sample value. Restricting to\n  // same-line whitespace makes such a line simply not match, so it correctly\n  // falls back to the type placeholder.\n  const regex = new RegExp(\n    `--[^\\\\S\\\\r\\\\n]*@param[^\\\\S\\\\r\\\\n]+(\\\\w+)[^\\\\S\\\\r\\\\n]+(${PARAM_TYPE_ALTERNATION})[^\\\\S\\\\r\\\\n]*=[^\\\\S\\\\r\\\\n]*(.+?)[^\\\\S\\\\r\\\\n]*$`,\n    \"gim\",\n  );\n  for (const match of sql.matchAll(regex)) {\n    const [, paramName, paramType, rawValue] = match;\n    const formatted = formatSampleValue(paramType, rawValue);\n    // A value that fails type validation is dropped, not substituted: the param\n    // then falls back to the safe type-based placeholder during DESCRIBE.\n    if (formatted !== null) {\n      defaults[paramName] = formatted;\n    }\n  }\n  return defaults;\n}\n\n/**\n * Replace `:param` placeholders with describe-time literals so `DESCRIBE QUERY`\n * can run without bound parameters. Resolution order per parameter:\n *   1. An explicit `-- @param name TYPE = value` sample value (wins), which lets\n *      dynamic table names via `IDENTIFIER(...)` resolve to a real table.\n *   2. Otherwise a placeholder default derived from the annotated/inferred type.\n * Placeholders inside string literals or comments are left untouched.\n */\nexport function substituteParametersForDescribe(sql: string): string {\n  const protectedRanges = getProtectedRanges(sql);\n  const annotatedTypes = extractParameterTypes(sql);\n  const inferredTypes = inferParameterTypes(sql, protectedRanges);\n  const parameterTypes = { ...inferredTypes, ...annotatedTypes };\n  const parameterDefaults = extractParameterDefaults(sql);\n  return sql.replace(\n    /(?<!:):([a-zA-Z_]\\w*)/g,\n    (original, paramName, offset) => {\n      if (isInsideProtectedRange(offset, protectedRanges)) {\n        return original;\n      }\n      const sampleValue = parameterDefaults[paramName];\n      if (sampleValue !== undefined) {\n        return sampleValue;\n      }\n      return defaultForType(parameterTypes[paramName]);\n    },\n  );\n}\n\n/**\n * Append a remediation hint when a DESCRIBE failure looks like a dynamic\n * identifier that couldn't be resolved: the query calls `IDENTIFIER(...)` and\n * has at least one parameter without a describe-time sample value. These fail\n * because typegen substitutes a placeholder default (e.g. `''`) that yields a\n * malformed or non-existent table name. Steering the user to the `= value`\n * annotation turns the fatal error into a one-line fix.\n */\nfunction withIdentifierHint(\n  error: { code?: string; message: string },\n  sql: string,\n): { code?: string; message: string } {\n  if (!/\\bIDENTIFIER\\s*\\(/i.test(sql)) {\n    return error;\n  }\n  const protectedRanges = getProtectedRanges(sql);\n  const params = extractParameters(sql, protectedRanges);\n  const defaults = extractParameterDefaults(sql);\n  const unresolved = params.filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p) && defaults[p] === undefined,\n  );\n  if (unresolved.length === 0) {\n    return error;\n  }\n  const example = unresolved[0];\n  return {\n    ...error,\n    message: `${error.message}\\n  Hint: this query uses IDENTIFIER() with parameter(s) ${unresolved\n      .map((p) => `:${p}`)\n      .join(\n        \", \",\n      )}. 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.`,\n  };\n}\n\n/**\n * Infer parameter types from positional context in SQL.\n * V1 only infers NUMERIC from patterns like LIMIT, OFFSET, TOP,\n * FETCH FIRST ... ROWS, and arithmetic operators.\n * Parameters inside string literals or SQL comments are ignored.\n */\nexport function inferParameterTypes(\n  sql: string,\n  ranges?: Array<[number, number]>,\n): Record<string, string> {\n  const inferred: Record<string, string> = {};\n  const protectedRanges = ranges ?? getProtectedRanges(sql);\n\n  for (const pattern of NUMERIC_PATTERNS) {\n    for (const match of sql.matchAll(pattern)) {\n      if (!isInsideProtectedRange(match.index, protectedRanges)) {\n        inferred[match[1]] = \"NUMERIC\";\n      }\n    }\n  }\n\n  return inferred;\n}\n\n/**\n * Generate query schemas from a folder of SQL files\n * It uses DESCRIBE QUERY to get the schema without executing the query\n * @param queryFolder - the folder containing the SQL files\n * @param warehouseId - the warehouse id to use for schema analysis\n * @param options - options for the query generation\n * @param options.noCache - if true, skip the cache and regenerate all types\n * @param options.mode - preflight policy: \"non-blocking\" never probes the\n *   warehouse and never describes (emits cached/`unknown` types and returns\n *   immediately), \"blocking\" waits for a starting warehouse and starts (then\n *   waits for) a stopped one, treating only a deleted/deleting warehouse as\n *   fatal. Defaults to \"non-blocking\".\n * @returns an array of query schemas\n */\nexport async function generateQueriesFromDescribe(\n  queryFolder: string,\n  warehouseId: string,\n  options: {\n    noCache?: boolean;\n    concurrency?: number;\n    mode?: PreflightMode;\n  } = {},\n): Promise<QueryGenerationResult> {\n  const {\n    noCache = false,\n    concurrency: rawConcurrency = 10,\n    mode = \"non-blocking\",\n  } = options;\n  const concurrency =\n    typeof rawConcurrency === \"number\" && Number.isFinite(rawConcurrency)\n      ? Math.max(1, Math.floor(rawConcurrency))\n      : 10;\n\n  // read all query files and cache in parallel\n  const [allFiles, cache] = await Promise.all([\n    fs.readdir(queryFolder),\n    noCache\n      ? ({ version: CACHE_VERSION, queries: {} } as Awaited<\n          ReturnType<typeof loadCache>\n        >)\n      : loadCache(),\n  ]);\n\n  const queryFiles = allFiles.filter((file) => file.endsWith(\".sql\"));\n  logger.debug(\"Found %d SQL queries\", queryFiles.length);\n\n  const client = new WorkspaceClient({});\n  const spinner = new Spinner();\n\n  // Read all SQL files in parallel\n  const sqlContents = await Promise.all(\n    queryFiles.map((file) => fs.readFile(path.join(queryFolder, file), \"utf8\")),\n  );\n\n  const startTime = performance.now();\n\n  // Phase 1: Check cache, separate cached vs uncached\n  const cachedResults: Array<{ index: number; schema: QuerySchema }> = [];\n  const uncachedQueries: Array<{\n    index: number;\n    queryName: string;\n    sql: string;\n    sqlHash: string;\n    cleanedSql: string;\n  }> = [];\n  const logEntries: Array<{\n    queryName: string;\n    status: \"HIT\" | \"MISS\";\n    // Absent for clean hits/misses. \"syntax\" = bad SQL on a reachable warehouse;\n    // \"connectivity\" = warehouse unreachable; \"empty\" = described but no columns;\n    // \"fatal\" = non-SQL setup/request failure surfaced after .d.ts emission.\n    kind?: \"syntax\" | \"connectivity\" | \"empty\" | \"fatal\";\n    error?: { code?: string; message: string };\n  }> = [];\n\n  for (let i = 0; i < queryFiles.length; i++) {\n    const file = queryFiles[i];\n    const rawName = path.basename(file, \".sql\");\n    const queryName = normalizeQueryName(rawName);\n\n    const sql = sqlContents[i];\n    const sqlHash = hashSQL(sql);\n\n    const cached = cache.queries[queryName];\n    if (cached && cached.hash === sqlHash && !cached.retry) {\n      cachedResults.push({\n        index: i,\n        schema: { name: queryName, type: cached.type },\n      });\n      logEntries.push({ queryName, status: \"HIT\" });\n    } else {\n      const protectedRanges = getProtectedRanges(sql);\n      const annotatedTypes = extractParameterTypes(sql);\n      const inferredTypes = inferParameterTypes(sql, protectedRanges);\n      const parameterTypes = { ...inferredTypes, ...annotatedTypes };\n      // substituteParametersForDescribe applies `-- @param name TYPE = value`\n      // sample values (e.g. for IDENTIFIER table names) ahead of type defaults;\n      // parameterDefaults is recomputed here only to skip them in the warn loop.\n      const parameterDefaults = extractParameterDefaults(sql);\n      const sqlWithDefaults = substituteParametersForDescribe(sql);\n\n      // Warn about unresolved parameters\n      const allParams = extractParameters(sql, protectedRanges);\n      for (const param of allParams) {\n        if (SERVER_INJECTED_PARAMS.includes(param)) continue;\n        if (parameterDefaults[param]) continue;\n        if (parameterTypes[param]) continue;\n        logger.warn(\n          '%s: parameter \":%s\" has no type annotation or inference. Add %s to the query file.',\n          queryFiles[i],\n          param,\n          `-- @param ${param} <TYPE>`,\n        );\n      }\n\n      const cleanedSql = sqlWithDefaults.trim().replace(/;\\s*$/, \"\");\n      uncachedQueries.push({ index: i, queryName, sql, sqlHash, cleanedSql });\n    }\n  }\n\n  // Phase 2: Execute all uncached DESCRIBE calls in parallel\n  type DescribeResult =\n    | {\n        // Described successfully with a result schema — the only case we cache.\n        status: \"ok\";\n        index: number;\n        schema: QuerySchema;\n        cacheEntry: { hash: string; type: string; retry: boolean };\n      }\n    | {\n        // Reachable warehouse ran DESCRIBE and rejected the statement — a\n        // genuine SQL error. Eligible to fail the build; never cached.\n        status: \"syntax\";\n        index: number;\n        schema: QuerySchema;\n        error: { code?: string; message: string };\n      }\n    | {\n        // DESCRIBE succeeded but returned no columns — soft `unknown`. Not a\n        // failure, not cached, retried next run.\n        status: \"empty\";\n        index: number;\n        schema: QuerySchema;\n      }\n    | {\n        // Warehouse reachable but returned a non-terminal state (PENDING/\n        // RUNNING) with no rows — stopped/cold-starting/busy. Degrade like a\n        // transient outage (reuse cache or `unknown`); not cached, not empty.\n        status: \"unavailable\";\n        index: number;\n        schema: QuerySchema;\n      };\n\n  const freshResults: Array<{ index: number; schema: QuerySchema }> = [];\n  // Genuine SQL errors (reachable warehouse). Connectivity failures are NOT\n  // recorded here — they degrade silently so a transient outage isn't fatal.\n  const syntaxErrors: QuerySyntaxError[] = [];\n  const fatalErrors: QueryFatalError[] = [];\n\n  if (uncachedQueries.length > 0) {\n    // One-time warehouse preflight (before issuing any DESCRIBE). A single\n    // warehouses.get classifies the warehouse so we can skip the whole describe\n    // batch when it can't serve this run, instead of letting every query fail\n    // (and re-fail next run). Reuses this file's degrade/classify helpers so a\n    // not-ready warehouse degrades exactly like a per-query outage.\n    let decision: ReturnType<typeof decidePreflight> = \"proceed\";\n    let fatalMessage = \"\";\n    if (mode === \"non-blocking\") {\n      // `non-blocking` never describes and must make ZERO warehouse round-trips:\n      // skip the probe entirely (no getWarehouseState) and go straight to\n      // degradeAll. A foreground/one-shot run can't describe in the background,\n      // so it emits best-available types (reused cache or `unknown`) and returns\n      // now.\n      decision = \"degradeAll\";\n    } else {\n      try {\n        const state = await getWarehouseState(client, warehouseId);\n        decision = decidePreflight(state, mode);\n        if (decision === \"fatal\") {\n          fatalMessage = `warehouse ${warehouseId} is ${state}`;\n        }\n        if (decision === \"startWaitProceed\") {\n          // Stopped/stopping warehouse: nudge it out of the stopped state, then\n          // poll to RUNNING. treatStoppedAsTransient rides out the stale\n          // pre-start STOPPED/STOPPING reading the start hasn't propagated past\n          // yet — only DELETED/DELETING (or the deadline) ends the wait early.\n          await startWarehouse(client, warehouseId);\n          const final = await waitUntilRunning(client, warehouseId, {\n            maxMs: PREFLIGHT_WAIT_MAX_MS,\n            treatStoppedAsTransient: true,\n          });\n          if (final === \"RUNNING\") {\n            decision = \"proceed\";\n          } else {\n            decision = \"fatal\";\n            fatalMessage = `warehouse ${warehouseId} did not reach RUNNING (now ${final})`;\n          }\n        }\n        if (decision === \"waitThenProceed\") {\n          const final = await waitUntilRunning(client, warehouseId, {\n            maxMs: PREFLIGHT_WAIT_MAX_MS,\n          });\n          if (final === \"RUNNING\") {\n            decision = \"proceed\";\n          } else {\n            decision = \"fatal\";\n            fatalMessage = `warehouse ${warehouseId} did not reach RUNNING (now ${final})`;\n          }\n        }\n      } catch (err) {\n        if (isConnectivityError(err)) {\n          // Warehouse unreachable (transient outage): degrade silently like a\n          // per-query connectivity failure — never fail a build on a blip.\n          decision = \"degradeAll\";\n        } else {\n          // Auth, bad warehouse id, malformed config, or a timed-out wait: fatal.\n          decision = \"fatal\";\n          fatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;\n        }\n      }\n    }\n\n    if (decision !== \"proceed\") {\n      // degradeAll or fatal: skip DESCRIBE entirely. Every uncached query gets a\n      // degraded schema (reused cache or `unknown`); fatal additionally records\n      // a fatalError per query so the caller fails the build after writing.\n      const kind = decision === \"fatal\" ? \"fatal\" : \"connectivity\";\n      for (const { index, queryName, sql, sqlHash } of uncachedQueries) {\n        freshResults.push({\n          index,\n          schema: {\n            name: queryName,\n            type: degradedType(cache, queryName, sql, sqlHash),\n          },\n        });\n        if (decision === \"fatal\") {\n          fatalErrors.push({ name: queryName, message: fatalMessage });\n          logEntries.push({\n            queryName,\n            status: \"MISS\",\n            kind,\n            error: { message: fatalMessage },\n          });\n        } else {\n          logEntries.push({ queryName, status: \"MISS\", kind });\n        }\n      }\n    } else {\n      let completed = 0;\n      const total = uncachedQueries.length;\n      spinner.start(\n        `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (0/${total})`,\n      );\n\n      // Shared across this run's DESCRIBE QUERY calls: discover the warehouse's\n      // result format once, then reuse it.\n      const describeFormat: DescribeFormatMemo = {};\n\n      const describeOne = async ({\n        index,\n        queryName,\n        sql,\n        sqlHash,\n        cleanedSql,\n      }: (typeof uncachedQueries)[number]): Promise<DescribeResult> => {\n        // describeAdaptive negotiates the result format with the warehouse\n        // (JSON_ARRAY for standard DBSQL, ARROW_STREAM for Reyden) and returns\n        // an already-normalized response, so the state classification below\n        // reads it directly.\n        const result = await describeAdaptive(\n          client,\n          `DESCRIBE QUERY ${cleanedSql}`,\n          warehouseId,\n          describeFormat,\n        );\n\n        completed++;\n        spinner.update(\n          `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (${completed}/${total})`,\n        );\n\n        logger.debug(\n          \"DESCRIBE result for %s: state=%s, rows=%d\",\n          queryName,\n          result.status.state,\n          result.result?.data_array?.length ?? 0,\n        );\n\n        if (result.status.state === \"FAILED\") {\n          // The warehouse was reachable and ran DESCRIBE, but the statement\n          // failed — a genuine SQL error (bad table, syntax, incompatible type).\n          const sqlError =\n            result.status.error?.message || \"Query execution failed\";\n          // The failure is surfaced once, formatted, by the aggregated\n          // TypegenSyntaxError (and the summary table) — don't also log the raw\n          // message here or every SQL error prints twice in dev.\n          const type = generateUnknownResultQuery(sql, queryName);\n          return {\n            status: \"syntax\",\n            index,\n            schema: { name: queryName, type },\n            error: withIdentifierHint(parseError(sqlError), sql),\n          };\n        }\n\n        if (result.status.state !== \"SUCCEEDED\") {\n          // Non-terminal state (PENDING/RUNNING) with no result rows: the\n          // warehouse is reachable but not ready (stopped, cold-starting, or\n          // busy). Degrade like a transient outage — reuse the last-good cached\n          // type when the SQL is unchanged, else emit `unknown`. Never \"empty\":\n          // treating this as empty would emit `result: unknown` AND discard the\n          // good cached type, silently throwing away working types.\n          return {\n            status: \"unavailable\",\n            index,\n            schema: {\n              name: queryName,\n              type: degradedType(cache, queryName, sql, sqlHash),\n            },\n          };\n        }\n\n        const { type, hasResults } = convertToQueryType(result, sql, queryName);\n        if (!hasResults) {\n          // Described, but no result columns. Emit `unknown` and retry next run;\n          // do not cache (we never persist `result: unknown`).\n          return { status: \"empty\", index, schema: { name: queryName, type } };\n        }\n        return {\n          status: \"ok\",\n          index,\n          schema: { name: queryName, type },\n          cacheEntry: { hash: sqlHash, type, retry: false },\n        };\n      };\n\n      // Process in chunks, saving cache after each chunk\n      const processBatchResults = (\n        settled: PromiseSettledResult<DescribeResult>[],\n        batchOffset: number,\n      ) => {\n        for (let i = 0; i < settled.length; i++) {\n          const entry = settled[i];\n          const { queryName } = uncachedQueries[batchOffset + i];\n\n          if (entry.status === \"fulfilled\") {\n            const res = entry.value;\n            freshResults.push({ index: res.index, schema: res.schema });\n\n            if (res.status === \"ok\") {\n              // Only a successful describe with a result schema is cached.\n              cache.queries[queryName] = res.cacheEntry;\n              logEntries.push({ queryName, status: \"MISS\" });\n            } else if (res.status === \"syntax\") {\n              // Genuine SQL error — record it for the caller's prod/dev gate.\n              // Not cached: re-described next run so a fixed query recovers.\n              syntaxErrors.push({\n                name: queryName,\n                message: res.error.message,\n              });\n              logEntries.push({\n                queryName,\n                status: \"MISS\",\n                kind: \"syntax\",\n                error: res.error,\n              });\n            } else if (res.status === \"empty\") {\n              // status === \"empty\": described, no columns. Soft unknown, not cached.\n              logEntries.push({ queryName, status: \"MISS\", kind: \"empty\" });\n            } else {\n              // status === \"unavailable\": non-terminal DESCRIBE (warehouse\n              // stopped/cold-starting/busy). Degrade like a transient outage:\n              // tag OFFLINE, count as degraded, never cache.\n              logEntries.push({\n                queryName,\n                status: \"MISS\",\n                kind: \"connectivity\",\n              });\n            }\n          } else {\n            // executeStatement rejected without a normal StatementExecution result.\n            // Only structured transport/connectivity failures are treated as\n            // offline; auth, bad warehouse IDs, malformed requests, and SDK/config\n            // failures stay fatal so users fix the underlying setup issue.\n            completed++;\n            spinner.update(\n              `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (${completed}/${total})`,\n            );\n\n            const { sql, sqlHash, index } = uncachedQueries[batchOffset + i];\n            const reason = getErrorDiagnostic(entry.reason);\n            const error = parseError(reason);\n            const priorEntry = cache.queries[queryName];\n            const canReusePrior =\n              priorEntry?.hash === sqlHash && !priorEntry.retry;\n            const type = degradedType(cache, queryName, sql, sqlHash);\n            freshResults.push({ index, schema: { name: queryName, type } });\n\n            if (!isConnectivityError(entry.reason)) {\n              fatalErrors.push({ name: queryName, message: error.message });\n              logEntries.push({\n                queryName,\n                status: \"MISS\",\n                kind: \"fatal\",\n                error,\n              });\n              continue;\n            }\n\n            logger.warn(\n              \"DESCRIBE unreachable for %s: %s — %s\",\n              queryName,\n              reason,\n              canReusePrior\n                ? \"reusing last cached type\"\n                : \"emitting unknown (no matching cache)\",\n            );\n            logEntries.push({\n              queryName,\n              status: \"MISS\",\n              kind: \"connectivity\",\n              error,\n            });\n          }\n        }\n      };\n\n      if (uncachedQueries.length > concurrency) {\n        for (let b = 0; b < uncachedQueries.length; b += concurrency) {\n          const batch = uncachedQueries.slice(b, b + concurrency);\n          const batchResults = await Promise.allSettled(batch.map(describeOne));\n          processBatchResults(batchResults, b);\n          await saveCache(cache);\n        }\n      } else {\n        const settled = await Promise.allSettled(\n          uncachedQueries.map(describeOne),\n        );\n        processBatchResults(settled, 0);\n        await saveCache(cache);\n      }\n\n      spinner.stop(\"\");\n    }\n  }\n\n  const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);\n\n  // Print formatted table\n  if (logEntries.length > 0) {\n    const maxNameLen = Math.max(...logEntries.map((e) => e.queryName.length));\n    const separator = pc.dim(\"─\".repeat(50));\n    console.log(\"\");\n    console.log(\n      `  ${pc.bold(\"Typegen Queries\")} ${pc.dim(`(${logEntries.length})`)}`,\n    );\n    console.log(`  ${separator}`);\n    for (const entry of logEntries) {\n      let tag: string;\n      switch (entry.kind) {\n        case \"syntax\":\n          tag = pc.bold(pc.red(\"SQL ERR\"));\n          break;\n        case \"connectivity\":\n          tag = pc.bold(pc.yellow(\"OFFLINE\"));\n          break;\n        case \"empty\":\n          tag = pc.dim(\"EMPTY  \");\n          break;\n        case \"fatal\":\n          tag = pc.bold(pc.red(\"FATAL \"));\n          break;\n        default:\n          tag =\n            entry.status === \"HIT\"\n              ? `cache ${pc.bold(pc.green(\"HIT  \"))}`\n              : `cache ${pc.bold(pc.yellow(\"MISS \"))}`;\n      }\n      const rawName = entry.queryName.padEnd(maxNameLen);\n      // Only genuine SQL errors are struck through. Connectivity/empty kept a\n      // usable type (reused or unknown), so they read as degraded, not broken.\n      const name =\n        entry.kind === \"syntax\" || entry.kind === \"fatal\"\n          ? pc.dim(pc.strikethrough(rawName))\n          : rawName;\n      const errorCode = entry.error?.message.match(/\\[([^\\]]+)\\]/)?.[1];\n      const reason = errorCode ? `  ${pc.dim(errorCode)}` : \"\";\n      console.log(`  ${tag}  ${name}${reason}`);\n    }\n    const newCount = logEntries.filter(\n      (e) => e.status === \"MISS\" && !e.kind,\n    ).length;\n    const cacheCount = logEntries.filter((e) => e.status === \"HIT\").length;\n    const syntaxCount = logEntries.filter((e) => e.kind === \"syntax\").length;\n    const offlineCount = logEntries.filter(\n      (e) => e.kind === \"connectivity\",\n    ).length;\n    const emptyCount = logEntries.filter((e) => e.kind === \"empty\").length;\n    const fatalCount = logEntries.filter((e) => e.kind === \"fatal\").length;\n    console.log(`  ${separator}`);\n    const parts = [`${newCount} new`, `${cacheCount} from cache`];\n    if (syntaxCount > 0)\n      parts.push(\n        `${syntaxCount} SQL ${syntaxCount === 1 ? \"error\" : \"errors\"}`,\n      );\n    if (offlineCount > 0) parts.push(`${offlineCount} degraded`);\n    if (emptyCount > 0) parts.push(`${emptyCount} empty`);\n    if (fatalCount > 0)\n      parts.push(\n        `${fatalCount} fatal ${fatalCount === 1 ? \"error\" : \"errors\"}`,\n      );\n    console.log(`  ${parts.join(\", \")}. ${pc.dim(`${elapsed}s`)}`);\n    console.log(\"\");\n  }\n\n  // Merge and sort by original file index for deterministic output\n  const schemas = [...cachedResults, ...freshResults]\n    .sort((a, b) => a.index - b.index)\n    .map((r) => r.schema);\n\n  return { schemas, syntaxErrors, fatalErrors };\n}\n\n/**\n * Normalize query name by removing the .obo extension\n * @param queryName - the query name to normalize\n * @returns the normalized query name\n */\nfunction normalizeQueryName(fileName: string): string {\n  return fileName.replace(/\\.obo$/, \"\");\n}\n\n/**\n * Normalize SQL type name by removing parameters/generics\n * Examples:\n *   DECIMAL(38,6) -> DECIMAL\n *   ARRAY<STRING> -> ARRAY\n *   MAP<STRING,INT> -> MAP\n *   STRUCT<name:STRING> -> STRUCT\n *   INTERVAL DAY TO SECOND -> INTERVAL\n *   GEOGRAPHY(4326) -> GEOGRAPHY\n */\nexport function normalizeTypeName(typeName: string): string {\n  return typeName\n    .replace(/\\(.*\\)$/, \"\") // remove (p, s) eg: DECIMAL(38,6) -> DECIMAL\n    .replace(/<.*>$/, \"\") // remove <T> eg: ARRAY<STRING> -> ARRAY\n    .split(\" \")[0]; // take first word eg: INTERVAL DAY TO SECOND -> INTERVAL\n}\n\n/** Type Map for Databricks data types to JavaScript types */\nconst typeMap: Record<string, string> = {\n  // string types\n  STRING: \"string\",\n  BINARY: \"string\",\n  // boolean\n  BOOLEAN: \"boolean\",\n  // numeric types\n  TINYINT: \"number\",\n  SMALLINT: \"number\",\n  INT: \"number\",\n  BIGINT: \"number\",\n  FLOAT: \"number\",\n  DOUBLE: \"number\",\n  DECIMAL: \"number\",\n  // date/time types\n  DATE: \"string\",\n  TIMESTAMP: \"string\",\n  TIMESTAMP_NTZ: \"string\",\n  INTERVAL: \"string\",\n  // complex types\n  ARRAY: \"unknown[]\",\n  MAP: \"Record<string, unknown>\",\n  STRUCT: \"Record<string, unknown>\",\n  OBJECT: \"Record<string, unknown>\",\n  VARIANT: \"unknown\",\n  // spatial types\n  GEOGRAPHY: \"unknown\",\n  GEOMETRY: \"unknown\",\n  // null type\n  VOID: \"null\",\n};\n"],"mappings":"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"}

package/dist/type-generator/statement-result.js

@@ -0,0 +1,116 @@
+import { createLogger } from "../logging/logger.js";
+import { getErrorMessage } from "./errors.js";
+
+//#region src/type-generator/statement-result.ts
+const logger = createLogger("type-generator:statement-result");
+/**
+* Normalize a Statement Execution response so downstream parsers can always
+* read rows from `result.data_array`, regardless of the wire format the
+* warehouse chose.
+*
+* `@databricks/sdk-experimental`'s `executeStatement` defaults to an
+* `ARROW_STREAM` disposition. With an `INLINE` disposition the single
+* DESCRIBE row is returned as a base64-encoded Arrow IPC stream in
+* `result.attachment` and `result.data_array` is left undefined. The metric
+* and query type generators only ever read `result.data_array`, so without
+* this normalization an Arrow response reads as "returned no rows" — the
+* registry ships empty and the runtime fail-closed gate 503s every affected
+* metric/query. (A warehouse configured to return `JSON_ARRAY` populates
+* `data_array` directly and needs no decoding — that path, and every mocked
+* test, flows through here unchanged.)
+*/
+async function normalizeResultRows(response) {
+	if (response.result?.next_chunk_index != null || response.result?.next_chunk_internal_link != null) throw new Error("DESCRIBE result is multi-chunk (truncated); refusing to emit partial types — see next_chunk_index");
+	if (response.result?.data_array !== void 0) return response;
+	const attachment = response.result?.attachment;
+	if (attachment === void 0) return response;
+	try {
+		const { tableFromIPC } = await import("apache-arrow");
+		const dataArray = tableFromIPC(Buffer.from(attachment, "base64")).toArray().map((row) => [...row].map(([, value]) => value == null ? null : String(value)));
+		return {
+			...response,
+			result: {
+				...response.result,
+				data_array: dataArray
+			}
+		};
+	} catch (err) {
+		logger.warn("failed to decode ARROW_STREAM DESCRIBE attachment (%s); emitting no rows — metric/query types may degrade", getErrorMessage(err));
+		return response;
+	}
+}
+/**
+* True when a failure means the warehouse REJECTED the requested result format
+* (so another format is worth trying), not that it ran the statement and hit a
+* real error. There is no single structured signal for this, so we combine two:
+*
+*  - `errorCode` — a statement that actually RAN and failed carries a SQL error
+*    code (`TABLE_OR_VIEW_NOT_FOUND`, `PARSE_SYNTAX_ERROR`, …); a request-shape
+*    rejection comes back as `INVALID_PARAMETER_VALUE`. Any other code means the
+*    statement ran, so it is never a format rejection — whatever its message
+*    text happens to contain. This gate matters because DESCRIBE runs over
+*    user-supplied SQL and analysis errors echo the offending SQL back: a source
+*    with columns named `disposition`/`format` would otherwise trip the message
+*    match below and get its real diagnostic masked by a pointless retry.
+*  - the message signatures — Reyden's `merge_json_arrays` (its `JSON_ARRAY`
+*    assembly fails on a `… AS JSON` single-cell result) and standard DBSQL's
+*    rejection of `ARROW_STREAM` under an `INLINE` disposition.
+*
+* A genuine SQL error, connectivity failure, or not-ready warehouse does NOT
+* match — those are returned/propagated for the caller's normal handling, never
+* re-tried. `errorCode` is optional: a thrown SDK error carries no reliable
+* structured code, so the catch-path caller passes message only.
+*/
+function isFormatRejection(message, errorCode) {
+	if (!message) return false;
+	if (errorCode && errorCode !== "INVALID_PARAMETER_VALUE") return false;
+	const m = message.toLowerCase();
+	return m.includes("merge_json_arrays") || m.includes("must be json_array") || m.includes("disposition") && m.includes("format");
+}
+/**
+* Run a DESCRIBE and return a response whose rows are readable via
+* `result.data_array`, adapting to the warehouse's result-format capability.
+*
+* No single format is portable: standard DBSQL (PRO/CLASSIC) serves
+* `INLINE`+`JSON_ARRAY` and rejects `INLINE`+`ARROW_STREAM`; the Reyden engine
+* is the inverse — it rejects `JSON_ARRAY` on a `… AS JSON` result
+* (`merge_json_arrays`) and only returns rows as an `INLINE`+`ARROW_STREAM`
+* attachment. We try `JSON_ARRAY` first (the documented default) and ONLY when
+* the warehouse rejects that format ({@link isFormatRejection}) fall back to
+* `ARROW_STREAM` (decoded by {@link normalizeResultRows}); the accepted format
+* is memoized so the rest of the run skips the probe. Any other outcome —
+* success, SQL error, degrade, connectivity failure — is returned or propagated
+* unchanged, exactly as a single executeStatement would.
+*/
+async function describeAdaptive(client, statement, warehouseId, memo) {
+	const formats = memo.format ? [memo.format] : ["JSON_ARRAY", "ARROW_STREAM"];
+	let lastResponse;
+	let lastError;
+	for (const format of formats) try {
+		const normalized = await normalizeResultRows(await client.statementExecution.executeStatement({
+			statement,
+			warehouse_id: warehouseId,
+			wait_timeout: "30s",
+			format,
+			disposition: "INLINE"
+		}));
+		if (normalized.status?.state === "FAILED" && isFormatRejection(normalized.status.error?.message, normalized.status.error?.error_code)) {
+			lastResponse = normalized;
+			continue;
+		}
+		if (normalized.status?.state === "SUCCEEDED") memo.format = format;
+		return normalized;
+	} catch (error) {
+		if (isFormatRejection(getErrorMessage(error))) {
+			lastError = error;
+			continue;
+		}
+		throw error;
+	}
+	if (lastResponse !== void 0) return lastResponse;
+	throw lastError;
+}
+
+//#endregion
+export { describeAdaptive };
+//# sourceMappingURL=statement-result.js.map

package/dist/type-generator/statement-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement-result.js","names":[],"sources":["../../src/type-generator/statement-result.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport { createLogger } from \"../logging/logger\";\nimport { getErrorMessage } from \"./errors\";\nimport type { DatabricksStatementExecutionResponse } from \"./types\";\n\nconst logger = createLogger(\"type-generator:statement-result\");\n\n/**\n * Normalize a Statement Execution response so downstream parsers can always\n * read rows from `result.data_array`, regardless of the wire format the\n * warehouse chose.\n *\n * `@databricks/sdk-experimental`'s `executeStatement` defaults to an\n * `ARROW_STREAM` disposition. With an `INLINE` disposition the single\n * DESCRIBE row is returned as a base64-encoded Arrow IPC stream in\n * `result.attachment` and `result.data_array` is left undefined. The metric\n * and query type generators only ever read `result.data_array`, so without\n * this normalization an Arrow response reads as \"returned no rows\" — the\n * registry ships empty and the runtime fail-closed gate 503s every affected\n * metric/query. (A warehouse configured to return `JSON_ARRAY` populates\n * `data_array` directly and needs no decoding — that path, and every mocked\n * test, flows through here unchanged.)\n */\nexport async function normalizeResultRows(\n  response: DatabricksStatementExecutionResponse,\n): Promise<DatabricksStatementExecutionResponse> {\n  // Truncation guard, above the passthrough so it runs on either transport. A\n  // result exceeding INLINE's size limit is paginated (`next_chunk_*` set) and\n  // we hold only the first chunk; emitting types from it would cache partial\n  // types. A deliberate throw — unlike the best-effort decode below — that both\n  // callers catch per-entry as a loud per-key/per-query failure.\n  if (\n    response.result?.next_chunk_index != null ||\n    response.result?.next_chunk_internal_link != null\n  ) {\n    throw new Error(\n      \"DESCRIBE result is multi-chunk (truncated); refusing to emit partial types — see next_chunk_index\",\n    );\n  }\n\n  // Passthrough: rows already materialized (JSON_ARRAY warehouses + every\n  // mocked test). `data_array` being an empty array still counts as present —\n  // that is a genuine \"no rows\" answer we must not overwrite with a decode.\n  if (response.result?.data_array !== undefined) {\n    return response;\n  }\n\n  const attachment = response.result?.attachment;\n  if (attachment === undefined) {\n    // No rows, no attachment: let the downstream \"no rows\" degrade path fire.\n    return response;\n  }\n\n  try {\n    // Lazy import: only pull apache-arrow into the process when an attachment\n    // genuinely needs decoding.\n    const { tableFromIPC } = await import(\"apache-arrow\");\n    const bytes = Buffer.from(attachment, \"base64\");\n    const table = tableFromIPC(bytes);\n    // Extract each cell in SCHEMA/FIELD order. Spreading a StructRow\n    // (`[...row]`) drives apache-arrow's StructRowIterator, which walks the\n    // struct's children by positional index and yields `[fieldName, value]`\n    // pairs in field order. We deliberately do NOT use `Object.values(row)`\n    // nor `row.toArray()`: both funnel through `Object.values` (toArray() is\n    // literally `Object.values(this.toJSON())` in apache-arrow@21), and\n    // `Object.values` re-sorts integer-like keys ascending per the ECMAScript\n    // spec — so an integer-named DESCRIBE column would scramble the positional\n    // `[col_name, data_type, comment]` order. The iterator is immune to that.\n    const dataArray: (string | null)[][] = table\n      .toArray()\n      .map((row) =>\n        [...(row as Iterable<[unknown, unknown]>)].map(([, value]) =>\n          value == null ? null : String(value),\n        ),\n      );\n\n    return {\n      ...response,\n      result: {\n        ...response.result,\n        data_array: dataArray,\n      },\n    };\n  } catch (err) {\n    // Best-effort: a corrupt/partial Arrow payload — or a missing apache-arrow\n    // module — must not crash the pass. Warn so a Reyden user whose decode failed\n    // gets a breadcrumb instead of mysteriously-empty types, then return the\n    // response unchanged: it routes into the deterministic \"no rows\" degrade.\n    logger.warn(\n      \"failed to decode ARROW_STREAM DESCRIBE attachment (%s); emitting no rows — metric/query types may degrade\",\n      getErrorMessage(err),\n    );\n    return response;\n  }\n}\n\n/** Result format the typegen requests for a DESCRIBE. */\ntype DescribeFormat = \"JSON_ARRAY\" | \"ARROW_STREAM\";\n\n/**\n * Per-path memo of the result format a warehouse accepts for a DESCRIBE shape.\n * Create one per describe path (metric / query) and reuse it across that path's\n * statements: a typegen run targets a single warehouse, so the working format\n * is discovered once and every later DESCRIBE skips the probe. NOT shared\n * across paths — `DESCRIBE QUERY` and `DESCRIBE … AS JSON` can differ (Reyden\n * fails `JSON_ARRAY` only for the single-cell `AS JSON` result).\n */\nexport interface DescribeFormatMemo {\n  format?: \"JSON_ARRAY\" | \"ARROW_STREAM\";\n}\n\n/**\n * True when a failure means the warehouse REJECTED the requested result format\n * (so another format is worth trying), not that it ran the statement and hit a\n * real error. There is no single structured signal for this, so we combine two:\n *\n *  - `errorCode` — a statement that actually RAN and failed carries a SQL error\n *    code (`TABLE_OR_VIEW_NOT_FOUND`, `PARSE_SYNTAX_ERROR`, …); a request-shape\n *    rejection comes back as `INVALID_PARAMETER_VALUE`. Any other code means the\n *    statement ran, so it is never a format rejection — whatever its message\n *    text happens to contain. This gate matters because DESCRIBE runs over\n *    user-supplied SQL and analysis errors echo the offending SQL back: a source\n *    with columns named `disposition`/`format` would otherwise trip the message\n *    match below and get its real diagnostic masked by a pointless retry.\n *  - the message signatures — Reyden's `merge_json_arrays` (its `JSON_ARRAY`\n *    assembly fails on a `… AS JSON` single-cell result) and standard DBSQL's\n *    rejection of `ARROW_STREAM` under an `INLINE` disposition.\n *\n * A genuine SQL error, connectivity failure, or not-ready warehouse does NOT\n * match — those are returned/propagated for the caller's normal handling, never\n * re-tried. `errorCode` is optional: a thrown SDK error carries no reliable\n * structured code, so the catch-path caller passes message only.\n */\nfunction isFormatRejection(\n  message: string | undefined,\n  errorCode?: string,\n): boolean {\n  if (!message) return false;\n  // It ran and produced a SQL error — never a format rejection, whatever the\n  // message text happens to contain.\n  if (errorCode && errorCode !== \"INVALID_PARAMETER_VALUE\") return false;\n  const m = message.toLowerCase();\n  return (\n    m.includes(\"merge_json_arrays\") ||\n    m.includes(\"must be json_array\") ||\n    (m.includes(\"disposition\") && m.includes(\"format\"))\n  );\n}\n\n/**\n * Run a DESCRIBE and return a response whose rows are readable via\n * `result.data_array`, adapting to the warehouse's result-format capability.\n *\n * No single format is portable: standard DBSQL (PRO/CLASSIC) serves\n * `INLINE`+`JSON_ARRAY` and rejects `INLINE`+`ARROW_STREAM`; the Reyden engine\n * is the inverse — it rejects `JSON_ARRAY` on a `… AS JSON` result\n * (`merge_json_arrays`) and only returns rows as an `INLINE`+`ARROW_STREAM`\n * attachment. We try `JSON_ARRAY` first (the documented default) and ONLY when\n * the warehouse rejects that format ({@link isFormatRejection}) fall back to\n * `ARROW_STREAM` (decoded by {@link normalizeResultRows}); the accepted format\n * is memoized so the rest of the run skips the probe. Any other outcome —\n * success, SQL error, degrade, connectivity failure — is returned or propagated\n * unchanged, exactly as a single executeStatement would.\n */\nexport async function describeAdaptive(\n  client: WorkspaceClient,\n  statement: string,\n  warehouseId: string,\n  memo: DescribeFormatMemo,\n): Promise<DatabricksStatementExecutionResponse> {\n  const formats: DescribeFormat[] = memo.format\n    ? [memo.format]\n    : [\"JSON_ARRAY\", \"ARROW_STREAM\"];\n  let lastResponse: DatabricksStatementExecutionResponse | undefined;\n  let lastError: unknown;\n  for (const format of formats) {\n    try {\n      const response = (await client.statementExecution.executeStatement({\n        statement,\n        warehouse_id: warehouseId,\n        // Synchronous wait: without it the call can return PENDING/RUNNING with\n        // no rows, which downstream misreads as a no-result degrade.\n        wait_timeout: \"30s\",\n        format,\n        disposition: \"INLINE\",\n      })) as DatabricksStatementExecutionResponse;\n      const normalized = await normalizeResultRows(response);\n      if (\n        normalized.status?.state === \"FAILED\" &&\n        isFormatRejection(\n          normalized.status.error?.message,\n          normalized.status.error?.error_code,\n        )\n      ) {\n        lastResponse = normalized;\n        continue; // warehouse rejected this format — try the next\n      }\n      if (normalized.status?.state === \"SUCCEEDED\") {\n        memo.format = format;\n      }\n      return normalized;\n    } catch (error) {\n      if (isFormatRejection(getErrorMessage(error))) {\n        lastError = error;\n        continue; // format rejected via a thrown error — try the next\n      }\n      throw error;\n    }\n  }\n  // Every attempted format was rejected. Surface the last outcome so the caller\n  // degrades / reports as usual.\n  if (lastResponse !== undefined) return lastResponse;\n  throw lastError;\n}\n"],"mappings":";;;;AAKA,MAAM,SAAS,aAAa,kCAAkC;;;;;;;;;;;;;;;;;AAkB9D,eAAsB,oBACpB,UAC+C;AAM/C,KACE,SAAS,QAAQ,oBAAoB,QACrC,SAAS,QAAQ,4BAA4B,KAE7C,OAAM,IAAI,MACR,oGACD;AAMH,KAAI,SAAS,QAAQ,eAAe,OAClC,QAAO;CAGT,MAAM,aAAa,SAAS,QAAQ;AACpC,KAAI,eAAe,OAEjB,QAAO;AAGT,KAAI;EAGF,MAAM,EAAE,iBAAiB,MAAM,OAAO;EAYtC,MAAM,YAVQ,aADA,OAAO,KAAK,YAAY,SAAS,CACd,CAW9B,SAAS,CACT,KAAK,QACJ,CAAC,GAAI,IAAqC,CAAC,KAAK,GAAG,WACjD,SAAS,OAAO,OAAO,OAAO,MAAM,CACrC,CACF;AAEH,SAAO;GACL,GAAG;GACH,QAAQ;IACN,GAAG,SAAS;IACZ,YAAY;IACb;GACF;UACM,KAAK;AAKZ,SAAO,KACL,6GACA,gBAAgB,IAAI,CACrB;AACD,SAAO;;;;;;;;;;;;;;;;;;;;;;;;;AAyCX,SAAS,kBACP,SACA,WACS;AACT,KAAI,CAAC,QAAS,QAAO;AAGrB,KAAI,aAAa,cAAc,0BAA2B,QAAO;CACjE,MAAM,IAAI,QAAQ,aAAa;AAC/B,QACE,EAAE,SAAS,oBAAoB,IAC/B,EAAE,SAAS,qBAAqB,IAC/B,EAAE,SAAS,cAAc,IAAI,EAAE,SAAS,SAAS;;;;;;;;;;;;;;;;;AAmBtD,eAAsB,iBACpB,QACA,WACA,aACA,MAC+C;CAC/C,MAAM,UAA4B,KAAK,SACnC,CAAC,KAAK,OAAO,GACb,CAAC,cAAc,eAAe;CAClC,IAAI;CACJ,IAAI;AACJ,MAAK,MAAM,UAAU,QACnB,KAAI;EAUF,MAAM,aAAa,MAAM,oBATP,MAAM,OAAO,mBAAmB,iBAAiB;GACjE;GACA,cAAc;GAGd,cAAc;GACd;GACA,aAAa;GACd,CAAC,CACoD;AACtD,MACE,WAAW,QAAQ,UAAU,YAC7B,kBACE,WAAW,OAAO,OAAO,SACzB,WAAW,OAAO,OAAO,WAC1B,EACD;AACA,kBAAe;AACf;;AAEF,MAAI,WAAW,QAAQ,UAAU,YAC/B,MAAK,SAAS;AAEhB,SAAO;UACA,OAAO;AACd,MAAI,kBAAkB,gBAAgB,MAAM,CAAC,EAAE;AAC7C,eAAY;AACZ;;AAEF,QAAM;;AAKV,KAAI,iBAAiB,OAAW,QAAO;AACvC,OAAM"}

package/dist/type-generator/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/type-generator/types.ts"],"sourcesContent":["/**\n * Databricks statement execution response interface for DESCRIBE QUERY\n * @property statement_id - the id of the statement\n * @property status - the status of the statement\n * @property result - the result containing column schema as rows [col_name, data_type, comment]\n */\nexport interface DatabricksStatementExecutionResponse {\n  statement_id: string;\n  status: {\n    state: string;\n    error?: { error_code?: string; message?: string };\n  };\n  result?: {\n    data_array?: (string | null)[][];\n  };\n}\n\n/**\n * Map of SQL types to their corresponding marker types\n * Used to convert SQL types to their corresponding marker types\n */\nexport const sqlTypeToMarker: Record<string, string> = {\n  // string\n  STRING: \"SQLStringMarker\",\n  BINARY: \"SQLBinaryMarker\",\n  // boolean\n  BOOLEAN: \"SQLBooleanMarker\",\n  // numeric\n  NUMERIC: \"SQLNumberMarker\",\n  INT: \"SQLNumberMarker\",\n  BIGINT: \"SQLNumberMarker\",\n  TINYINT: \"SQLNumberMarker\",\n  SMALLINT: \"SQLNumberMarker\",\n  FLOAT: \"SQLNumberMarker\",\n  DOUBLE: \"SQLNumberMarker\",\n  DECIMAL: \"SQLNumberMarker\",\n  // date/time\n  DATE: \"SQLDateMarker\",\n  TIMESTAMP: \"SQLTimestampMarker\",\n  TIMESTAMP_NTZ: \"SQLTimestampMarker\",\n};\n\n/**\n * Map of SQL types to their corresponding helper function names\n * Used to generate JSDoc hints for parameters\n */\nexport const sqlTypeToHelper: Record<string, string> = {\n  // string\n  STRING: \"sql.string()\",\n  BINARY: \"sql.binary()\",\n  // boolean\n  BOOLEAN: \"sql.boolean()\",\n  // numeric — route each SQL type to its closest typed helper. INT/BIGINT\n  // are critical for LIMIT/OFFSET; FLOAT/DOUBLE preserve precision intent;\n  // NUMERIC/DECIMAL route to sql.numeric() for exact-decimal columns.\n  NUMERIC: \"sql.numeric()\",\n  DECIMAL: \"sql.numeric()\",\n  BIGINT: \"sql.bigint()\",\n  INT: \"sql.int()\",\n  TINYINT: \"sql.int()\",\n  SMALLINT: \"sql.int()\",\n  FLOAT: \"sql.float()\",\n  DOUBLE: \"sql.double()\",\n  // date/time\n  DATE: \"sql.date()\",\n  TIMESTAMP: \"sql.timestamp()\",\n  TIMESTAMP_NTZ: \"sql.timestamp()\",\n};\n\n/**\n * Query schema interface\n * @property name - the name of the query\n * @property type - the type of the query (string, number, boolean, object, array, etc.)\n */\nexport interface QuerySchema {\n  name: string;\n  type: string;\n}\n\n/**\n * A genuine SQL error: `DESCRIBE QUERY` ran against a *reachable* warehouse and\n * the warehouse reported the statement as FAILED (bad table, syntax error,\n * incompatible type, …). Distinct from a connectivity failure (warehouse\n * unreachable), which is non-fatal and never recorded here.\n * @property name - the query name\n * @property message - the SQL error message reported by the warehouse\n */\nexport interface QuerySyntaxError {\n  name: string;\n  message: string;\n}\n\n/**\n * A non-SQL fatal error while attempting to describe a query: authentication,\n * authorization, invalid warehouse/configuration, malformed SDK request, or\n * any other setup problem that should not be treated as an offline warehouse.\n * @property name - the query name\n * @property message - the fatal error message\n */\nexport interface QueryFatalError {\n  name: string;\n  message: string;\n}\n\n/**\n * Result of describing a folder of queries.\n * @property schemas - one schema per query, in original file order. Queries that\n *   could not be described carry `result: unknown` so output stays valid.\n * @property syntaxErrors - queries whose DESCRIBE failed against a reachable\n *   warehouse (genuine SQL errors). Connectivity failures are deliberately NOT\n *   included: they degrade silently (reuse last-known-good type or emit\n *   `unknown`) so a transient outage never fails a build.\n * @property fatalErrors - non-SQL fatal describe request failures. These still\n *   produce `result: unknown` schemas so callers can write declarations before\n *   surfacing the error.\n */\nexport interface QueryGenerationResult {\n  schemas: QuerySchema[];\n  syntaxErrors: QuerySyntaxError[];\n  fatalErrors: QueryFatalError[];\n}\n"],"mappings":";;;;;AAqBA,MAAa,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB;;;;;AAMD,MAAa,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAIT,SAAS;CACT,SAAS;CACT,QAAQ;CACR,KAAK;CACL,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CAER,MAAM;CACN,WAAW;CACX,eAAe;CAChB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/type-generator/types.ts"],"sourcesContent":["/**\n * Databricks statement execution response interface for DESCRIBE QUERY /\n * DESCRIBE TABLE EXTENDED.\n *\n * Two result shapes matter here:\n *  - `result.data_array` — rows already materialized as JSON arrays. Present\n *    when the warehouse returns `JSON_ARRAY` (and what every mocked test\n *    builds).\n *  - `result.attachment` — a base64-encoded Arrow IPC stream. Present when the\n *    statement runs with `format: \"ARROW_STREAM\"` + `disposition: \"INLINE\"`,\n *    which is the SDK's default disposition. The single row lands here and\n *    `data_array` is left undefined. {@link normalizeResultRows} decodes this\n *    back into `data_array` so downstream parsers stay shape-agnostic.\n *\n * @property statement_id - the id of the statement\n * @property status - the status of the statement\n * @property manifest - result metadata; `manifest.format` echoes the wire\n *   format (`ARROW_STREAM`, `JSON_ARRAY`, ...) the warehouse chose.\n * @property result - the result; either `data_array` (rows as\n *   `[col_name, data_type, comment]` arrays) or `attachment` (base64 Arrow IPC)\n */\nexport interface DatabricksStatementExecutionResponse {\n  statement_id: string;\n  status: {\n    state: string;\n    error?: { error_code?: string; message?: string };\n  };\n  manifest?: {\n    format?: string;\n  };\n  result?: {\n    data_array?: (string | null)[][];\n    /** Base64-encoded Arrow IPC stream (ARROW_STREAM + INLINE disposition). */\n    attachment?: string;\n    /**\n     * Set when the result spans multiple chunks (rows exceeded INLINE's size\n     * limit). Its presence means this response holds only the FIRST chunk;\n     * {@link normalizeResultRows} throws rather than emit truncated types.\n     */\n    next_chunk_index?: number;\n    /** Companion to {@link next_chunk_index}: link to fetch the next chunk. */\n    next_chunk_internal_link?: string;\n  };\n}\n\n/**\n * Map of SQL types to their corresponding marker types\n * Used to convert SQL types to their corresponding marker types\n */\nexport const sqlTypeToMarker: Record<string, string> = {\n  // string\n  STRING: \"SQLStringMarker\",\n  BINARY: \"SQLBinaryMarker\",\n  // boolean\n  BOOLEAN: \"SQLBooleanMarker\",\n  // numeric\n  NUMERIC: \"SQLNumberMarker\",\n  INT: \"SQLNumberMarker\",\n  BIGINT: \"SQLNumberMarker\",\n  TINYINT: \"SQLNumberMarker\",\n  SMALLINT: \"SQLNumberMarker\",\n  FLOAT: \"SQLNumberMarker\",\n  DOUBLE: \"SQLNumberMarker\",\n  DECIMAL: \"SQLNumberMarker\",\n  // date/time\n  DATE: \"SQLDateMarker\",\n  TIMESTAMP: \"SQLTimestampMarker\",\n  TIMESTAMP_NTZ: \"SQLTimestampMarker\",\n};\n\n/**\n * Map of SQL types to their corresponding helper function names\n * Used to generate JSDoc hints for parameters\n */\nexport const sqlTypeToHelper: Record<string, string> = {\n  // string\n  STRING: \"sql.string()\",\n  BINARY: \"sql.binary()\",\n  // boolean\n  BOOLEAN: \"sql.boolean()\",\n  // numeric — route each SQL type to its closest typed helper. INT/BIGINT\n  // are critical for LIMIT/OFFSET; FLOAT/DOUBLE preserve precision intent;\n  // NUMERIC/DECIMAL route to sql.numeric() for exact-decimal columns.\n  NUMERIC: \"sql.numeric()\",\n  DECIMAL: \"sql.numeric()\",\n  BIGINT: \"sql.bigint()\",\n  INT: \"sql.int()\",\n  TINYINT: \"sql.int()\",\n  SMALLINT: \"sql.int()\",\n  FLOAT: \"sql.float()\",\n  DOUBLE: \"sql.double()\",\n  // date/time\n  DATE: \"sql.date()\",\n  TIMESTAMP: \"sql.timestamp()\",\n  TIMESTAMP_NTZ: \"sql.timestamp()\",\n};\n\n/**\n * Query schema interface\n * @property name - the name of the query\n * @property type - the type of the query (string, number, boolean, object, array, etc.)\n */\nexport interface QuerySchema {\n  name: string;\n  type: string;\n}\n\n/**\n * A genuine SQL error: `DESCRIBE QUERY` ran against a *reachable* warehouse and\n * the warehouse reported the statement as FAILED (bad table, syntax error,\n * incompatible type, …). Distinct from a connectivity failure (warehouse\n * unreachable), which is non-fatal and never recorded here.\n * @property name - the query name\n * @property message - the SQL error message reported by the warehouse\n */\nexport interface QuerySyntaxError {\n  name: string;\n  message: string;\n}\n\n/**\n * A non-SQL fatal error while attempting to describe a query: authentication,\n * authorization, invalid warehouse/configuration, malformed SDK request, or\n * any other setup problem that should not be treated as an offline warehouse.\n * @property name - the query name\n * @property message - the fatal error message\n */\nexport interface QueryFatalError {\n  name: string;\n  message: string;\n}\n\n/**\n * Result of describing a folder of queries.\n * @property schemas - one schema per query, in original file order. Queries that\n *   could not be described carry `result: unknown` so output stays valid.\n * @property syntaxErrors - queries whose DESCRIBE failed against a reachable\n *   warehouse (genuine SQL errors). Connectivity failures are deliberately NOT\n *   included: they degrade silently (reuse last-known-good type or emit\n *   `unknown`) so a transient outage never fails a build.\n * @property fatalErrors - non-SQL fatal describe request failures. These still\n *   produce `result: unknown` schemas so callers can write declarations before\n *   surfacing the error.\n */\nexport interface QueryGenerationResult {\n  schemas: QuerySchema[];\n  syntaxErrors: QuerySyntaxError[];\n  fatalErrors: QueryFatalError[];\n}\n"],"mappings":";;;;;AAiDA,MAAa,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB;;;;;AAMD,MAAa,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAIT,SAAS;CACT,SAAS;CACT,QAAQ;CACR,KAAK;CACL,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CAER,MAAM;CACN,WAAW;CACX,eAAe;CAChB"}

package/dist/type-generator/vite-plugin.d.ts

@@ -6,6 +6,18 @@ import { Plugin } from "vite";
  */
 interface AppKitTypesPluginOptions {
   outFile?: string;
+  /**
+   * Path to the metric registry d.ts file (relative to client folder).
+   * Defaults to a sibling of `outFile`, computed by the generator.
+   */
+  mvOutFile?: string;
+  /**
+   * Path to the metric semantic-metadata JSON file (relative to client folder).
+   * Build-time artifact — defaults to a sibling of {@link mvOutFile}
+   * (itself a sibling of `outFile`), computed by the generator. Skipped
+   * automatically when `metric-views.json` is absent.
+   */
+  mvMetadataOutFile?: string;
   /** Folders to watch for changes. */
   watchFolders?: string[];
 }

package/dist/type-generator/vite-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.d.ts","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"mappings":";;;;;AAGmC;UA6BzB,wBAAA;EAER,OAAA;EAAA;EAEA,YAAA;AAAA;;;;;;;iBASc,iBAAA,CAAkB,OAAA,GAAU,wBAAA,GAA2B,MAAA"}
+{"version":3,"file":"vite-plugin.d.ts","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"mappings":";;;;;AAGmC;UA6BzB,wBAAA;EAER,OAAA;EAFgC;;;;EAOhC,SAAA;EASY;;AASd;;;;EAXE,iBAAA;EAWgC;EAThC,YAAA;AAAA;;;;;;;iBASc,iBAAA,CAAkB,OAAA,GAAU,wBAAA,GAA2B,MAAA"}

package/dist/type-generator/vite-plugin.js

@@ -22,6 +22,8 @@ const DEV_WAREHOUSE_WATCH_MAX_MS = 6e4;
 */
 function appKitTypesPlugin(options) {
 	let outFile;
+	let mvOutFile;
+	let mvMetadataOutFile;
 	let watchFolders;
 	let inFlight = null;
 	let queued = false;
@@ -50,7 +52,9 @@ function appKitTypesPlugin(options) {
 				queryFolder: watchFolders[0],
 				warehouseId,
 				noCache: false,
-				mode
+				mode,
+				mvOutFile,
+				mvMetadataOutFile
 			});
 		} catch (error) {
 			const isTypegenError = error instanceof TypegenSyntaxError || error instanceof TypegenFatalError;
@@ -106,9 +110,9 @@ function appKitTypesPlugin(options) {
 	*
 	* Post-probe behaviour by state:
 	*  - RUNNING → describe right away (the dev foreground degraded, so a running
-	*    warehouse would otherwise never get real types — this is the case Phase 3
-	*    restores). `waitUntilRunning` returns immediately for an already-running
-	*    warehouse, then the blocking regenerate fires.
+	*    warehouse would otherwise never get real types). `waitUntilRunning`
+	*    returns immediately for an already-running warehouse, then the blocking
+	*    regenerate fires.
 	*  - STARTING → it's already coming up; just wait for RUNNING, then describe.
 	*  - STOPPED / STOPPING → kick off a start, wait for RUNNING, then describe.
 	*  - DELETED / DELETING → return (a deleted warehouse can't be started, and
@@ -171,6 +175,8 @@ function appKitTypesPlugin(options) {
 		configResolved(config) {
 			const projectRoot = path.resolve(config.root, "..");
 			outFile = path.resolve(projectRoot, options?.outFile ?? `shared/${TYPES_DIR}/${ANALYTICS_TYPES_FILE}`);
+			mvOutFile = options?.mvOutFile !== void 0 ? path.resolve(projectRoot, options.mvOutFile) : void 0;
+			mvMetadataOutFile = options?.mvMetadataOutFile !== void 0 ? path.resolve(projectRoot, options.mvMetadataOutFile) : void 0;
 			watchFolders = options?.watchFolders ?? [path.join(process.cwd(), "config", "queries")];
 		},
 		buildStart() {
@@ -181,7 +187,7 @@ function appKitTypesPlugin(options) {
 		configureServer(server) {
 			server.watcher.add(watchFolders);
 			server.watcher.on("change", (changedFile) => {
-				if (watchFolders.some((folder) => changedFile.startsWith(folder)) && changedFile.endsWith(".sql")) {
+				if (watchFolders.some((folder) => changedFile.startsWith(folder)) && (changedFile.endsWith(".sql") || path.basename(changedFile) === "metric-views.json")) {
 					runGenerate("non-blocking");
 					armWarehouseWatch();
 				}

package/dist/type-generator/vite-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.js","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":["import { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { Plugin } from \"vite\";\nimport { createLogger } from \"../logging/logger\";\nimport {\n  ANALYTICS_TYPES_FILE,\n  generateFromEntryPoint,\n  TYPES_DIR,\n  TypegenFatalError,\n  TypegenSyntaxError,\n} from \"./index\";\nimport type { PreflightMode } from \"./preflight\";\nimport {\n  getWarehouseState,\n  startWarehouse,\n  waitUntilRunning,\n} from \"./warehouse-status\";\n\nconst logger = createLogger(\"type-generator:vite-plugin\");\n\n/**\n * How long the DEV background watcher waits for a STARTING warehouse to reach\n * RUNNING before giving up. Short relative to the CLI's preflight budget: this\n * is a best-effort \"regenerate once the warehouse warms up\" convenience, not a\n * gate, so we'd rather stop polling than hold a detached task open for minutes.\n */\nconst DEV_WAREHOUSE_WATCH_MAX_MS = 60_000;\n\n/**\n * Options for the AppKit types plugin.\n */\ninterface AppKitTypesPluginOptions {\n  /* Path to the output d.ts file (relative to client folder). */\n  outFile?: string;\n  /** Folders to watch for changes. */\n  watchFolders?: string[];\n}\n\n/**\n * Vite plugin to generate types for AppKit queries.\n * Calls generateFromEntryPoint under the hood.\n * @param options - Options to override default values.\n * @returns Vite plugin to generate types for AppKit queries.\n */\nexport function appKitTypesPlugin(options?: AppKitTypesPluginOptions): Plugin {\n  let outFile: string;\n  let watchFolders: string[];\n\n  // Single-flight state for runGenerate(). `inFlight` is the promise of the\n  // currently-running drain (null when idle); `queued` records that a trigger\n  // arrived while a run was active so exactly ONE trailing run fires afterwards\n  // (latest-wins — coalesces any number of overlapping triggers into a single\n  // rerun). `queued` is read/cleared synchronously inside the drain loop so a\n  // trigger landing in any window is caught before the drain exits.\n  //\n  // `pendingMode` is the mode the next generate should run in (latest-wins, like\n  // `queued`): the foreground build runs non-blocking in dev (instant degrade)\n  // while the background warehouse watch runs blocking (real DESCRIBEs). A\n  // blocking watch trigger that lands while a non-blocking foreground run is in\n  // flight therefore still describes when its trailing run fires.\n  let inFlight: Promise<void> | null = null;\n  let queued = false;\n  let pendingMode: PreflightMode = \"non-blocking\";\n\n  // The currently-armed DEV background warehouse watch, if any. Aborting it\n  // stops a pending waitUntilRunning (server shutdown, or a newer arm replacing\n  // an older one).\n  let watchController: AbortController | null = null;\n\n  /**\n   * Generate types once in the given preflight {@link PreflightMode}. Never\n   * throws in dev (logs instead); in production it rethrows so the build fails.\n   * This is the un-guarded core — callers should go through {@link runGenerate}\n   * so concurrent triggers can't race-write the .d.ts.\n   *\n   * @param mode - preflight policy for this run. The foreground build passes a\n   *   NODE_ENV-derived mode (blocking in production, non-blocking in dev so it\n   *   degrades instantly); the background warehouse watch passes \"blocking\" so\n   *   its regenerate actually DESCRIBEs and lands real (non-degraded) types.\n   */\n  async function generateOnce(mode: PreflightMode) {\n    try {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return;\n      }\n\n      await generateFromEntryPoint({\n        outFile,\n        queryFolder: watchFolders[0],\n        warehouseId,\n        noCache: false,\n        mode,\n      });\n    } catch (error) {\n      // TypegenSyntaxError / TypegenFatalError carry a complete, actionable\n      // report in their message. Their stack frames and attached query arrays\n      // point into appkit internals and only add noise, so surface just the\n      // message — both when failing the prod build and when logging in dev.\n      const isTypegenError =\n        error instanceof TypegenSyntaxError ||\n        error instanceof TypegenFatalError;\n\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        if (isTypegenError) error.stack = error.message;\n        throw error;\n      }\n\n      if (isTypegenError) {\n        logger.error(\"%s\", error.message);\n      } else {\n        logger.error(\"Error generating types: %O\", error);\n      }\n    }\n  }\n\n  /**\n   * Single-flight wrapper around {@link generateOnce}. The initial build, the\n   * .sql watcher, and the DEV warehouse watch all route through here so they can\n   * never run typegen concurrently (which would race-write the .d.ts).\n   *\n   * If a run is already in flight, this does NOT start a second one — it records\n   * the requested mode and sets a trailing flag so exactly one more run fires\n   * after the current finishes, coalescing any number of overlapping triggers\n   * (latest-wins, including the mode: a blocking watch trigger that arrives mid\n   * non-blocking foreground run still describes when its trailing run fires).\n   *\n   * @param mode - preflight policy for this run. Recorded into `pendingMode`,\n   *   which the drain reads for each generate (latest trigger wins).\n   * @returns A promise that resolves when this trigger's work (including any\n   *   trailing run it scheduled) has completed.\n   */\n  function runGenerate(mode: PreflightMode): Promise<void> {\n    pendingMode = mode;\n\n    if (inFlight) {\n      // A run is active: remember that another trigger arrived and ride out the\n      // current run. One trailing run then covers all coalesced triggers and\n      // runs in the latest requested mode (recorded above).\n      queued = true;\n      return inFlight;\n    }\n\n    // Drain in a loop rather than recursing after a single queued-check: a\n    // trigger can land in the window between generateOnce() resolving and the\n    // check, so we re-test `queued` until it's clear. Critically, `inFlight` is\n    // cleared synchronously in the SAME tick as the final `queued === false`\n    // observation — never deferred to a .finally microtask — so there's no\n    // window where a trigger sees `inFlight` set but the drain has already\n    // decided to exit. The guard stays held for the whole drain, so concurrent\n    // triggers only ever set the flag; they never start a parallel generate.\n    const drain = async (): Promise<void> => {\n      while (true) {\n        queued = false;\n        // Snapshot the mode synchronously alongside clearing `queued` so a\n        // trigger landing during this generate is observed (via `queued`) on the\n        // next loop with its own mode, not silently dropped.\n        const runMode = pendingMode;\n        await generateOnce(runMode);\n        // Synchronous check + clear, atomic w.r.t. other (synchronous) callers.\n        if (!queued) {\n          inFlight = null;\n          return;\n        }\n      }\n    };\n\n    inFlight = drain();\n    return inFlight;\n  }\n\n  /**\n   * DEV-only: get the warehouse to RUNNING in the background and regenerate with\n   * real (non-degraded) types once it is — without blocking dev startup. The\n   * foreground build only ever degrades in dev (instant `unknown`/cached types),\n   * so this is what lands actual DESCRIBE results in the editor for EVERY\n   * reachable warehouse state, not just one that happens to already be warm.\n   *\n   * Post-probe behaviour by state:\n   *  - RUNNING → describe right away (the dev foreground degraded, so a running\n   *    warehouse would otherwise never get real types — this is the case Phase 3\n   *    restores). `waitUntilRunning` returns immediately for an already-running\n   *    warehouse, then the blocking regenerate fires.\n   *  - STARTING → it's already coming up; just wait for RUNNING, then describe.\n   *  - STOPPED / STOPPING → kick off a start, wait for RUNNING, then describe.\n   *  - DELETED / DELETING → return (a deleted warehouse can't be started, and\n   *    blocking typegen would treat it as fatal); leave the degraded types.\n   *\n   * No-op in production or without a warehouse id. Replaces any previously-armed\n   * watch (aborting it first). Fully self-contained: it never throws into the\n   * caller and never re-arms itself. The whole lifecycle is abortable via the\n   * shared {@link watchController} — its signal is threaded into\n   * `waitUntilRunning`, so a dev-server shutdown cancels a pending wait — and the\n   * regenerate routes through {@link runGenerate} so it can't race-write the\n   * .d.ts with the foreground degrade or a `.sql` re-trigger.\n   *\n   * The regenerate runs in \"blocking\" mode (not the foreground's non-blocking)\n   * so it actually DESCRIBEs the now-RUNNING warehouse and lands real types —\n   * the whole point of warming the warehouse in the background.\n   */\n  function armWarehouseWatch(): void {\n    if (process.env.NODE_ENV === \"production\") return;\n\n    const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n    if (!warehouseId) return;\n\n    // Supersede any in-flight watch so we never run two concurrently.\n    watchController?.abort();\n    const controller = new AbortController();\n    watchController = controller;\n    const { signal } = controller;\n\n    void (async () => {\n      try {\n        const client = new WorkspaceClient({});\n        const state = await getWarehouseState(client, warehouseId);\n\n        // A deleted/deleting warehouse can't be started and blocking typegen\n        // would treat it as fatal — leave the degraded types and stop. Every\n        // other state (including RUNNING) proceeds to wait-then-describe so the\n        // dev editor gets real types, not just the foreground's degraded ones.\n        if (state === \"DELETED\" || state === \"DELETING\") {\n          return;\n        }\n\n        // Stopped/stopping won't reach RUNNING on its own — nudge it. RUNNING and\n        // STARTING need no start (RUNNING is already up; STARTING is coming up),\n        // so don't issue a redundant one. A failed start is non-fatal: give up\n        // silently rather than throw out of the detached task (the developer\n        // still has degraded/cached types).\n        let startedByUs = false;\n        if (state === \"STOPPED\" || state === \"STOPPING\") {\n          try {\n            logger.debug(\"Warehouse is %s; starting it.\", state);\n            await startWarehouse(client, warehouseId);\n            startedByUs = true;\n          } catch {\n            return;\n          }\n        }\n\n        // Wait for RUNNING. For an already-RUNNING warehouse this returns on the\n        // first poll; for STARTING/STOPPED it polls (abortably) until the\n        // warehouse warms up, a terminal state, or the deadline.\n        const final = await waitUntilRunning(client, warehouseId, {\n          maxMs: DEV_WAREHOUSE_WATCH_MAX_MS,\n          signal,\n          // We just issued the start, so the first poll(s) often still report\n          // STOPPED/STOPPING before the start propagates. Poll through those\n          // instead of bailing, or the regenerate would never fire. When we\n          // didn't start it (RUNNING/STARTING branch), keep the default terminal\n          // states.\n          treatStoppedAsTransient: startedByUs,\n        });\n\n        if (final === \"RUNNING\" && !signal.aborted) {\n          logger.debug(\"Warehouse is RUNNING; regenerating types.\");\n          // Blocking: the warehouse is RUNNING now, so describe it and emit real\n          // (non-degraded) types — unlike the foreground dev run, which degraded.\n          // Routed through the single-flight guard so it coalesces with the\n          // foreground degrade / any `.sql` re-trigger instead of racing them.\n          await runGenerate(\"blocking\");\n        }\n      } catch {\n        // Detached background task: any failure (timeout, abort, connectivity,\n        // auth) is non-fatal — the developer still has degraded/cached types.\n      }\n    })();\n  }\n\n  return {\n    name: \"appkit-types\",\n\n    apply() {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return false;\n      }\n\n      if (!existsSync(path.join(process.cwd(), \"config\", \"queries\"))) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      const projectRoot = path.resolve(config.root, \"..\");\n      outFile = path.resolve(\n        projectRoot,\n        options?.outFile ?? `shared/${TYPES_DIR}/${ANALYTICS_TYPES_FILE}`,\n      );\n      watchFolders = options?.watchFolders ?? [\n        path.join(process.cwd(), \"config\", \"queries\"),\n      ];\n    },\n\n    buildStart() {\n      // Production: block the build on this generate (and surface failures).\n      // The watch is a dev-only no-op, so just run typegen.\n      if (process.env.NODE_ENV === \"production\") {\n        return runGenerate(\"blocking\");\n      }\n\n      // Dev: don't block startup waiting on typegen. The foreground generate runs\n      // non-blocking — it skips the warehouse entirely and writes degraded\n      // (cached/`unknown`) types instantly. Then arm the warehouse watch so the\n      // warehouse gets a one-shot BLOCKING regenerate (real types) in the\n      // background for EVERY reachable state: RUNNING describes right away, while\n      // STARTING/STOPPED are waited (and started) until they reach RUNNING.\n      void runGenerate(\"non-blocking\");\n      armWarehouseWatch();\n    },\n\n    configureServer(server) {\n      server.watcher.add(watchFolders);\n\n      server.watcher.on(\"change\", (changedFile) => {\n        const isWatchedFile = watchFolders.some((folder) =>\n          changedFile.startsWith(folder),\n        );\n\n        if (isWatchedFile && changedFile.endsWith(\".sql\")) {\n          // Route through the single-flight runner (was fire-and-forget\n          // generate(), which could race the initial build / watch). This is a\n          // dev-only hook, so degrade instantly (non-blocking), then re-arm the\n          // warehouse watch so the edited query is re-described in the background\n          // against the running warehouse (or once a still-starting one warms\n          // up), landing fresh blocking-described types.\n          void runGenerate(\"non-blocking\");\n          armWarehouseWatch();\n        }\n      });\n\n      // Tear down any pending warehouse watch when the dev server closes so a\n      // long backoff can't keep the process alive after shutdown.\n      server.httpServer?.once(\"close\", () => {\n        watchController?.abort();\n      });\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"vite-plugin.js","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":["import { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { Plugin } from \"vite\";\nimport { createLogger } from \"../logging/logger\";\nimport {\n  ANALYTICS_TYPES_FILE,\n  generateFromEntryPoint,\n  TYPES_DIR,\n  TypegenFatalError,\n  TypegenSyntaxError,\n} from \"./index\";\nimport type { PreflightMode } from \"./preflight\";\nimport {\n  getWarehouseState,\n  startWarehouse,\n  waitUntilRunning,\n} from \"./warehouse-status\";\n\nconst logger = createLogger(\"type-generator:vite-plugin\");\n\n/**\n * How long the DEV background watcher waits for a STARTING warehouse to reach\n * RUNNING before giving up. Short relative to the CLI's preflight budget: this\n * is a best-effort \"regenerate once the warehouse warms up\" convenience, not a\n * gate, so we'd rather stop polling than hold a detached task open for minutes.\n */\nconst DEV_WAREHOUSE_WATCH_MAX_MS = 60_000;\n\n/**\n * Options for the AppKit types plugin.\n */\ninterface AppKitTypesPluginOptions {\n  /* Path to the output d.ts file (relative to client folder). */\n  outFile?: string;\n  /**\n   * Path to the metric registry d.ts file (relative to client folder).\n   * Defaults to a sibling of `outFile`, computed by the generator.\n   */\n  mvOutFile?: string;\n  /**\n   * Path to the metric semantic-metadata JSON file (relative to client folder).\n   * Build-time artifact — defaults to a sibling of {@link mvOutFile}\n   * (itself a sibling of `outFile`), computed by the generator. Skipped\n   * automatically when `metric-views.json` is absent.\n   */\n  mvMetadataOutFile?: string;\n  /** Folders to watch for changes. */\n  watchFolders?: string[];\n}\n\n/**\n * Vite plugin to generate types for AppKit queries.\n * Calls generateFromEntryPoint under the hood.\n * @param options - Options to override default values.\n * @returns Vite plugin to generate types for AppKit queries.\n */\nexport function appKitTypesPlugin(options?: AppKitTypesPluginOptions): Plugin {\n  let outFile: string;\n  let mvOutFile: string | undefined;\n  let mvMetadataOutFile: string | undefined;\n  let watchFolders: string[];\n\n  // Single-flight state for runGenerate(). `inFlight` is the promise of the\n  // currently-running drain (null when idle); `queued` records that a trigger\n  // arrived while a run was active so exactly ONE trailing run fires afterwards\n  // (latest-wins — coalesces any number of overlapping triggers into a single\n  // rerun). `queued` is read/cleared synchronously inside the drain loop so a\n  // trigger landing in any window is caught before the drain exits.\n  //\n  // `pendingMode` is the mode the next generate should run in (latest-wins, like\n  // `queued`): the foreground build runs non-blocking in dev (instant degrade)\n  // while the background warehouse watch runs blocking (real DESCRIBEs). A\n  // blocking watch trigger that lands while a non-blocking foreground run is in\n  // flight therefore still describes when its trailing run fires.\n  let inFlight: Promise<void> | null = null;\n  let queued = false;\n  let pendingMode: PreflightMode = \"non-blocking\";\n\n  // The currently-armed DEV background warehouse watch, if any. Aborting it\n  // stops a pending waitUntilRunning (server shutdown, or a newer arm replacing\n  // an older one).\n  let watchController: AbortController | null = null;\n\n  /**\n   * Generate types once in the given preflight {@link PreflightMode}. Never\n   * throws in dev (logs instead); in production it rethrows so the build fails.\n   * This is the un-guarded core — callers should go through {@link runGenerate}\n   * so concurrent triggers can't race-write the .d.ts.\n   *\n   * @param mode - preflight policy for this run. The foreground build passes a\n   *   NODE_ENV-derived mode (blocking in production, non-blocking in dev so it\n   *   degrades instantly); the background warehouse watch passes \"blocking\" so\n   *   its regenerate actually DESCRIBEs and lands real (non-degraded) types.\n   */\n  async function generateOnce(mode: PreflightMode) {\n    try {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return;\n      }\n\n      await generateFromEntryPoint({\n        outFile,\n        queryFolder: watchFolders[0],\n        warehouseId,\n        noCache: false,\n        mode,\n        mvOutFile,\n        mvMetadataOutFile,\n      });\n    } catch (error) {\n      // TypegenSyntaxError / TypegenFatalError carry a complete, actionable\n      // report in their message. Their stack frames and attached query arrays\n      // point into appkit internals and only add noise, so surface just the\n      // message — both when failing the prod build and when logging in dev.\n      const isTypegenError =\n        error instanceof TypegenSyntaxError ||\n        error instanceof TypegenFatalError;\n\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        if (isTypegenError) error.stack = error.message;\n        throw error;\n      }\n\n      if (isTypegenError) {\n        logger.error(\"%s\", error.message);\n      } else {\n        logger.error(\"Error generating types: %O\", error);\n      }\n    }\n  }\n\n  /**\n   * Single-flight wrapper around {@link generateOnce}. The initial build, the\n   * .sql watcher, and the DEV warehouse watch all route through here so they can\n   * never run typegen concurrently (which would race-write the .d.ts).\n   *\n   * If a run is already in flight, this does NOT start a second one — it records\n   * the requested mode and sets a trailing flag so exactly one more run fires\n   * after the current finishes, coalescing any number of overlapping triggers\n   * (latest-wins, including the mode: a blocking watch trigger that arrives mid\n   * non-blocking foreground run still describes when its trailing run fires).\n   *\n   * @param mode - preflight policy for this run. Recorded into `pendingMode`,\n   *   which the drain reads for each generate (latest trigger wins).\n   * @returns A promise that resolves when this trigger's work (including any\n   *   trailing run it scheduled) has completed.\n   */\n  function runGenerate(mode: PreflightMode): Promise<void> {\n    pendingMode = mode;\n\n    if (inFlight) {\n      // A run is active: remember that another trigger arrived and ride out the\n      // current run. One trailing run then covers all coalesced triggers and\n      // runs in the latest requested mode (recorded above).\n      queued = true;\n      return inFlight;\n    }\n\n    // Drain in a loop rather than recursing after a single queued-check: a\n    // trigger can land in the window between generateOnce() resolving and the\n    // check, so we re-test `queued` until it's clear. Critically, `inFlight` is\n    // cleared synchronously in the SAME tick as the final `queued === false`\n    // observation — never deferred to a .finally microtask — so there's no\n    // window where a trigger sees `inFlight` set but the drain has already\n    // decided to exit. The guard stays held for the whole drain, so concurrent\n    // triggers only ever set the flag; they never start a parallel generate.\n    const drain = async (): Promise<void> => {\n      while (true) {\n        queued = false;\n        // Snapshot the mode synchronously alongside clearing `queued` so a\n        // trigger landing during this generate is observed (via `queued`) on the\n        // next loop with its own mode, not silently dropped.\n        const runMode = pendingMode;\n        await generateOnce(runMode);\n        // Synchronous check + clear, atomic w.r.t. other (synchronous) callers.\n        if (!queued) {\n          inFlight = null;\n          return;\n        }\n      }\n    };\n\n    inFlight = drain();\n    return inFlight;\n  }\n\n  /**\n   * DEV-only: get the warehouse to RUNNING in the background and regenerate with\n   * real (non-degraded) types once it is — without blocking dev startup. The\n   * foreground build only ever degrades in dev (instant `unknown`/cached types),\n   * so this is what lands actual DESCRIBE results in the editor for EVERY\n   * reachable warehouse state, not just one that happens to already be warm.\n   *\n   * Post-probe behaviour by state:\n   *  - RUNNING → describe right away (the dev foreground degraded, so a running\n   *    warehouse would otherwise never get real types). `waitUntilRunning`\n   *    returns immediately for an already-running warehouse, then the blocking\n   *    regenerate fires.\n   *  - STARTING → it's already coming up; just wait for RUNNING, then describe.\n   *  - STOPPED / STOPPING → kick off a start, wait for RUNNING, then describe.\n   *  - DELETED / DELETING → return (a deleted warehouse can't be started, and\n   *    blocking typegen would treat it as fatal); leave the degraded types.\n   *\n   * No-op in production or without a warehouse id. Replaces any previously-armed\n   * watch (aborting it first). Fully self-contained: it never throws into the\n   * caller and never re-arms itself. The whole lifecycle is abortable via the\n   * shared {@link watchController} — its signal is threaded into\n   * `waitUntilRunning`, so a dev-server shutdown cancels a pending wait — and the\n   * regenerate routes through {@link runGenerate} so it can't race-write the\n   * .d.ts with the foreground degrade or a `.sql` re-trigger.\n   *\n   * The regenerate runs in \"blocking\" mode (not the foreground's non-blocking)\n   * so it actually DESCRIBEs the now-RUNNING warehouse and lands real types —\n   * the whole point of warming the warehouse in the background.\n   */\n  function armWarehouseWatch(): void {\n    if (process.env.NODE_ENV === \"production\") return;\n\n    const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n    if (!warehouseId) return;\n\n    // Supersede any in-flight watch so we never run two concurrently.\n    watchController?.abort();\n    const controller = new AbortController();\n    watchController = controller;\n    const { signal } = controller;\n\n    void (async () => {\n      try {\n        const client = new WorkspaceClient({});\n        const state = await getWarehouseState(client, warehouseId);\n\n        // A deleted/deleting warehouse can't be started and blocking typegen\n        // would treat it as fatal — leave the degraded types and stop. Every\n        // other state (including RUNNING) proceeds to wait-then-describe so the\n        // dev editor gets real types, not just the foreground's degraded ones.\n        if (state === \"DELETED\" || state === \"DELETING\") {\n          return;\n        }\n\n        // Stopped/stopping won't reach RUNNING on its own — nudge it. RUNNING and\n        // STARTING need no start (RUNNING is already up; STARTING is coming up),\n        // so don't issue a redundant one. A failed start is non-fatal: give up\n        // silently rather than throw out of the detached task (the developer\n        // still has degraded/cached types).\n        let startedByUs = false;\n        if (state === \"STOPPED\" || state === \"STOPPING\") {\n          try {\n            logger.debug(\"Warehouse is %s; starting it.\", state);\n            await startWarehouse(client, warehouseId);\n            startedByUs = true;\n          } catch {\n            return;\n          }\n        }\n\n        // Wait for RUNNING. For an already-RUNNING warehouse this returns on the\n        // first poll; for STARTING/STOPPED it polls (abortably) until the\n        // warehouse warms up, a terminal state, or the deadline.\n        const final = await waitUntilRunning(client, warehouseId, {\n          maxMs: DEV_WAREHOUSE_WATCH_MAX_MS,\n          signal,\n          // We just issued the start, so the first poll(s) often still report\n          // STOPPED/STOPPING before the start propagates. Poll through those\n          // instead of bailing, or the regenerate would never fire. When we\n          // didn't start it (RUNNING/STARTING branch), keep the default terminal\n          // states.\n          treatStoppedAsTransient: startedByUs,\n        });\n\n        if (final === \"RUNNING\" && !signal.aborted) {\n          logger.debug(\"Warehouse is RUNNING; regenerating types.\");\n          // Blocking: the warehouse is RUNNING now, so describe it and emit real\n          // (non-degraded) types — unlike the foreground dev run, which degraded.\n          // Routed through the single-flight guard so it coalesces with the\n          // foreground degrade / any `.sql` re-trigger instead of racing them.\n          await runGenerate(\"blocking\");\n        }\n      } catch {\n        // Detached background task: any failure (timeout, abort, connectivity,\n        // auth) is non-fatal — the developer still has degraded/cached types.\n      }\n    })();\n  }\n\n  return {\n    name: \"appkit-types\",\n\n    apply() {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return false;\n      }\n\n      if (!existsSync(path.join(process.cwd(), \"config\", \"queries\"))) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      const projectRoot = path.resolve(config.root, \"..\");\n      outFile = path.resolve(\n        projectRoot,\n        options?.outFile ?? `shared/${TYPES_DIR}/${ANALYTICS_TYPES_FILE}`,\n      );\n      // Metric out-paths resolve against projectRoot only when explicitly\n      // provided; unset options pass through as undefined so the generator\n      // computes its sibling-of-outFile defaults. In the all-defaults case\n      // the final paths are identical (the default outFile above lives in\n      // shared/<TYPES_DIR>/), and a customized outFile now keeps its metric\n      // siblings next to it instead of pinning them under shared/.\n      mvOutFile =\n        options?.mvOutFile !== undefined\n          ? path.resolve(projectRoot, options.mvOutFile)\n          : undefined;\n      mvMetadataOutFile =\n        options?.mvMetadataOutFile !== undefined\n          ? path.resolve(projectRoot, options.mvMetadataOutFile)\n          : undefined;\n      watchFolders = options?.watchFolders ?? [\n        path.join(process.cwd(), \"config\", \"queries\"),\n      ];\n    },\n\n    buildStart() {\n      // Production: block the build on this generate (and surface failures).\n      // The watch is a dev-only no-op, so just run typegen.\n      if (process.env.NODE_ENV === \"production\") {\n        return runGenerate(\"blocking\");\n      }\n\n      // Dev: don't block startup waiting on typegen. The foreground generate runs\n      // non-blocking — it skips the warehouse entirely and writes degraded\n      // (cached/`unknown`) types instantly. Then arm the warehouse watch so the\n      // warehouse gets a one-shot BLOCKING regenerate (real types) in the\n      // background for EVERY reachable state: RUNNING describes right away, while\n      // STARTING/STOPPED are waited (and started) until they reach RUNNING.\n      void runGenerate(\"non-blocking\");\n      armWarehouseWatch();\n    },\n\n    configureServer(server) {\n      server.watcher.add(watchFolders);\n\n      server.watcher.on(\"change\", (changedFile) => {\n        const isWatchedFile = watchFolders.some((folder) =>\n          changedFile.startsWith(folder),\n        );\n\n        if (\n          isWatchedFile &&\n          (changedFile.endsWith(\".sql\") ||\n            // Basename equality, not endsWith: a sibling like\n            // \"legacy-metric-views.json\" must not trigger a regenerate —\n            // only the real config file does.\n            path.basename(changedFile) === \"metric-views.json\")\n        ) {\n          // Route through the single-flight runner (was fire-and-forget\n          // generate(), which could race the initial build / watch). This is a\n          // dev-only hook, so degrade instantly (non-blocking), then re-arm the\n          // warehouse watch so the edited query or metric-view source is\n          // re-described in the background against the running warehouse (or\n          // once a still-starting one warms up), landing fresh\n          // blocking-described types.\n          void runGenerate(\"non-blocking\");\n          armWarehouseWatch();\n        }\n      });\n\n      // Tear down any pending warehouse watch when the dev server closes so a\n      // long backoff can't keep the process alive after shutdown.\n      server.httpServer?.once(\"close\", () => {\n        watchController?.abort();\n      });\n    },\n  };\n}\n"],"mappings":"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"}

package/docs/development/type-generation.md

@@ -96,6 +96,10 @@ The type generator:
 4. Generates TypeScript interfaces for query parameters and results
 5. Creates a `QueryRegistry` type for type-safe query execution
 
+### Parameters during `DESCRIBE QUERY`[​](#parameters-during-describe-query "Direct link to parameters-during-describe-query")
+
+Type generation describes each query without binding real parameters, so it substitutes a placeholder default for every `:param` (e.g. `''` for a string). That breaks queries whose shape depends on a value — most notably dynamic table names via `IDENTIFIER(:catalog || '.schema.table')`. Annotate such parameters with a sample value (`-- @param catalog STRING = main`) so the describe call can resolve a real table. The sample value is used only at type-generation time; the runtime query still binds the actual parameter. See [SQL parameters → Sample values](./docs/plugins/analytics.md#sample-values-for-type-generation).
+
 ## Using generated types[​](#using-generated-types "Direct link to Using generated types")
 
 Once types are generated, your IDE will provide autocomplete and type checking: