fix(appkit): escape generated JSDoc, log Arrow decode failures, tidy mv doc comments

Review cleanups — two small safety fixes plus doc tidy, no behavior change
otherwise:

- escape "*/" in the generated @sqlType JSDoc sinks (render-types.ts and
  query-registry.ts) so a SQL type/comment containing "*/" can't close the
  comment early and corrupt the emitted .d.ts (S3).
- warn instead of silently swallowing an ARROW_STREAM decode failure in
  normalizeResultRows, so a Reyden user whose decode failed gets a breadcrumb
  rather than mysteriously-empty types (S2).

Doc tidy: MAX_METRIC_VIEWS rationale (N5), fix the self-referential
"legacy {@link MV_CONFIG_FILE}" comment (N2), drop the non-resolving @link in
sync.ts (N3), correct the stale "metric.json" header in the shared schema +
regenerate the JSON Schema (N4), un-strand a doc comment inside
resolveMetricConfig (N10), and replace the non-standard @note + redundant path
literals (N11).

Co-authored-by: Isaac
Signed-off-by: Atila Fassina <atila@fassina.eu>

Author: atilafassina

docs/static/schemas/metric-source.schema.json

@@ -21,7 +21,8 @@ import type {
 const MV_CONFIG_FILE = "metric-views.json";
 
 /**
- * {@link resolveMetricConfig} enforces these caps.
+ * Safety cap on declared metric views — a typo / DoS guard, NOT a Unity Catalog
+ * limit. Enforced by {@link resolveMetricConfig}.
  */
 const MAX_METRIC_VIEWS = 200;
 /** Per-segment cap = UC's object-name length limit (255). */
@@ -33,10 +34,10 @@ const FQN_SEGMENT_NAMES = ["catalog", "schema", "metric_view"] as const;
 const FQN_SEGMENT_COUNT = FQN_SEGMENT_NAMES.length;
 
 /**
- * Locale-independent comparator (UTF-16 code-unit order)
- * shared by BOTH artifact key orderings.
- *
- * @note important for caching correctness.
+ * Locale-independent comparator (UTF-16 code-unit order) shared by BOTH artifact
+ * key orderings. Plain `sort()` is locale-sensitive, so keys could order
+ * differently across environments and invalidate the cache hash — this keeps the
+ * ordering stable everywhere.
  */
 export function compareKeys(a: string, b: string): number {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -47,7 +48,7 @@ export function compareKeys(a: string, b: string): number {
  *
  * Returns `null` if the file does not exist (the metric-view path is
  * additive — apps without metric-views.json must not be penalized). There is
- * deliberately no fallback to the legacy {@link MV_CONFIG_FILE} filename.
+ * deliberately no fallback to the legacy `metric.json` filename.
  *
  * Throws on JSON parse errors so misconfiguration surfaces loudly.
  */
@@ -85,9 +86,9 @@ export async function readMetricConfig(
 
 /**
  * Validate a key against the JSON Schema's metricKey pattern. Kept
- * lightweight — the shared Zod schema ({@link metricSourceSchema} in `packages/shared/src/schemas/metric-source.ts`)
- * is the canonical contract for IDE/CI; this regex is identical to its
- * {@link metricKeySchema} in `packages/shared/src/schemas/metric-source.ts`.
+ * lightweight — the shared Zod schema ({@link metricSourceSchema}) is the
+ * canonical contract for IDE/CI; this regex is identical to its
+ * {@link metricKeySchema}.
  */
 function isValidMetricKey(key: string): boolean {
   return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key);
@@ -134,11 +135,9 @@ export function resolveMetricConfig(
     }
   }
 
-  /**
-   *  Default ONLY a genuinely-absent {@link MetricSourceConfig.metricViews}. `null` must fall through
-   * to the type check below and throw — the canonical Zod schema ({@link metricSourceSchema}) rejects
-   * `null`.
-   */
+  // Default to {} only when metricViews is genuinely absent. A `null` must fall
+  // through to the type check below and throw — the canonical Zod schema rejects
+  // null.
   const metricViews =
     config.metricViews === undefined ? {} : config.metricViews;
   if (

packages/appkit/src/type-generator/mv-registry/config.ts

@@ -44,7 +44,7 @@ function renderMetricEntry(schema: MetricSchema): string {
         const grainComment = col.timeGrains?.length
           ? ` @timeGrain ${col.timeGrains.join("|")}`
           : "";
-        return `${indent}/** @sqlType ${col.type}${grainComment} */
+        return `${indent}/** @sqlType ${col.type.replace(/\*\//g, "* /")}${grainComment} */
 ${indent}${JSON.stringify(col.name)}: ${tsTypeFor(col.type)}`;
       })
       .join(";\n");

packages/appkit/src/type-generator/mv-registry/render-types.ts

@@ -43,7 +43,7 @@ interface MetricDescribeOutcome {
 }
 
 /**
- * Run schema synchronization for every entry in {@link import("./config").MV_CONFIG_FILE}.
+ * Run schema synchronization for every entry in `metric-views.json`.
  */
 export async function syncMetrics(
   resolution: MetricConfigResolution,

packages/appkit/src/type-generator/mv-registry/sync.ts

@@ -172,8 +172,8 @@ export function convertToQueryType(
 
     // generate comment for column
     const comment = column.comment
-      ? `/** ${column.comment} */\n      `
-      : `/** @sqlType ${column.type_name} */\n      `;
+      ? `/** ${column.comment.replace(/\*\//g, "* /")} */\n      `
+      : `/** @sqlType ${column.type_name.replace(/\*\//g, "* /")} */\n      `;
 
     return `${comment}${name}: ${mappedType}`;
   });

packages/appkit/src/type-generator/query-registry.ts

@@ -1,7 +1,10 @@
 import type { WorkspaceClient } from "@databricks/sdk-experimental";
+import { createLogger } from "../logging/logger";
 import { getErrorMessage } from "./errors";
 import type { DatabricksStatementExecutionResponse } from "./types";
 
+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
@@ -78,9 +81,15 @@ export async function normalizeResultRows(
         data_array: dataArray,
       },
     };
-  } catch {
-    // Best-effort: a corrupt/partial Arrow payload must not crash the pass.
-    // Returning it unchanged routes into the deterministic "no rows" degrade.
+  } catch (err) {
+    // Best-effort: a corrupt/partial Arrow payload — or a missing apache-arrow
+    // module — must not crash the pass. Warn so a Reyden user whose decode failed
+    // gets a breadcrumb instead of mysteriously-empty types, then return the
+    // response unchanged: it routes into the deterministic "no rows" degrade.
+    logger.warn(
+      "failed to decode ARROW_STREAM DESCRIBE attachment (%s); emitting no rows — metric/query types may degrade",
+      getErrorMessage(err),
+    );
     return response;
   }
 }

packages/appkit/src/type-generator/statement-result.ts

@@ -1,10 +1,10 @@
 /**
  * AppKit metric-source schema.
  *
- * Single source of truth for `metric.json`
+ * Single source of truth for `metric-views.json`
  * the config that activates the Analytics' metric-view path.
  *
- * `metric.json` declares UC Metric Views under a single `metricViews` map.
+ * `metric-views.json` declares UC Metric Views under a single `metricViews` map.
  * Each entry binds a metric key to a UC metric view FQN plus the executor
  * the query runs as:
  * - `executor: "app_service_principal"` (default) — queried as the app service
@@ -93,7 +93,7 @@ export const metricSourceSchema = z
   })
   .strict()
   .describe(
-    "Schema for AppKit metric.json — declares Unity Catalog Metric View sources for the analytics plugin's metric-view path. Each entry under 'metricViews' binds a metric key to a UC metric view FQN and an executor ('app_service_principal' shared cache, or 'user' per-user cache). Object form (rather than bare string) at v1 enables future per-entry option growth without breaking changes.",
+    "Schema for AppKit metric-views.json — declares Unity Catalog Metric View sources for the analytics plugin's metric-view path. Each entry under 'metricViews' binds a metric key to a UC metric view FQN and an executor ('app_service_principal' shared cache, or 'user' per-user cache). Object form (rather than bare string) at v1 enables future per-entry option growth without breaking changes.",
   );
 
 export type MetricKey = z.infer<typeof metricKeySchema>;