chore: CLI typegen for Metric Views

[atilafassina]

Metric-view types are generated by generate-types itself — the same command (and Vite plugin) that produces query types. When a config/queries/metric-views.json is present, the run DESCRIBEs each declared UC Metric View and emits metric-views.d.ts alongside the query types; when it's absent the path stays dormant and nothing is emitted.

Note

Dormant feature, still not user-facing. Apps opt in only by adding metric-views.json. The runtime metric path (route, SQL engine, useMetricView hook) lands in later PRs of the stack — this PR is the type generator only.

What changed

This PR started as a standalone appkit mv sync command and was folded into generate-types instead — there is no separate metric-view command. This keeps one entry point for all typegen (queries, serving, metric-views), one warehouse round-trip, and one cache.

generateFromEntryPoint delegates metric emission to appkit's syncMetricViewsTypes export (readMetricConfig → resolveMetricConfig → syncMetrics → write metric-views.d.ts), reusing the existing metric writers, the adaptive DESCRIBE fetcher, and the post-#433 persistent cache helpers (loadCache / saveCache / metricCacheHash). The shared CLI reaches it through the same dynamic import("@databricks/appkit/type-generator") pattern generate-types already uses, so shared keeps no static dependency on appkit; the ambient shim narrows to just generateFromEntryPoint / generateServingTypes.

One emitted artifact: metric-views.d.ts

The generator emits a single file — metric-views.d.ts — which augments the MetricRegistry interface so useMetricView('<key>', …) is autocompleted and type-checked. It is compile-time only (erased at build). Each view's measures, dimensions, key unions (measureKeys/dimensionKeys/timeGrains), and per-column semantic metadata (SQL type, display_name, format, time_grain) are all encoded at the type level, including in a type-level metadata: block.

Why no runtime metadata bundle

An earlier iteration also emitted a metric-views.metadata.json runtime bundle (a Record<key, { measures, dimensions }> value shipped in the client bundle). That was dropped. It was a reader-less artifact on the current stack: nothing consumes it at runtime — its intended consumer lands with the runtime metric path in a later PR, not here. Rather than pre-position a runtime artifact whose shape the (not-yet-existent) consumer should drive, this PR ships types only. The single-source end-state — one generated artifact from which both the compile-time types and runtime validation derive (e.g. a generated Zod/Standard-Schema module) — is deferred to the runtime PR, where the consumer contract is real. See the removal of mv-registry/metadata.ts.

Behaviour

• Dormant by default — no metric-views.json ⇒ nothing emitted, exit 0. Adopting metric views is purely additive; apps that don't use them see no new files and no noise.
• Warehouse-readiness contract — identical to query types. In the default non-blocking run a view that can't be described yet (cold warehouse, or a bad/unreachable source) is written with permissive types + a warning; under --wait that same situation fails the build so CI never ships incomplete metric types.
• Fail-fast validation — a malformed metric-views.json (invalid JSON, or a source that isn't a three-part UC FQN) throws in every mode; it's the only way the metric path throws.

metric-views.json is keyed by metric key; each entry names the three-part UC FQN of the view and, optionally, the executor it runs as:

{
  "metricViews": {
    "revenue": { "source": "catalog.schema.revenue_metrics" },
    "customers": { "source": "catalog.schema.customer_metrics", "executor": "user" }
  }
}

Versioning policy (committed vs generated)

Everything under shared/appkit-types/ is a build artifact; the versioned input is config/queries/* (including metric-views.json).

• Template gitignores metric-views.d.ts (next to serving.d.ts) — scaffolded apps regenerate it at build via prebuild: generate-types --wait before vite build bakes the types into the bundle.
• dev-playground tracks metric-views.d.ts alongside its already-tracked analytics.d.ts, so the metric-view types are visible in-repo as a demo/reference. serving.d.ts stays gitignored (per-developer, endpoint-specific). The source metric-views.json is tracked either way.

Documented in docs/docs/development/type-generation.md.

[github-actions]

🔬  Run evals on this PR  ·  Go to Evals Monitor →

[Copilot]

Pull request overview

Adds a new appkit mv sync CLI surface (in packages/shared) that can generate Metric View type artifacts outside the Vite dev loop, backed by a new/expanded syncMetricViewsTypes export in @databricks/appkit/type-generator and a refactor to reuse the same unified metric sync pipeline from both the CLI and generateFromEntryPoint.

Changes:

• Add appkit mv sync command with interactive/non-interactive flows, schema validation, dormancy behavior, and cache controls.
• Introduce/extend syncMetricViewsTypes in the appkit type-generator and refactor generateFromEntryPoint to delegate Metric View emission to it.
• Standardize Metric View artifact filenames to metric-views.d.ts and metric-views.metadata.json, updating tests accordingly.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/shared/src/cli/index.ts	Wires the new mv parent command into the shared CLI.
packages/shared/src/cli/commands/type-generator.d.ts	Extends the ambient optional @databricks/appkit/type-generator declaration with syncMetricViewsTypes + metric artifact constants.
packages/shared/src/cli/commands/metric-views/index.ts	Adds the mv parent command and attaches the sync subcommand.
packages/shared/src/cli/commands/metric-views/validate-metric-views-source.ts	Adds Zod-based validation and CLI-friendly formatting for metric-views.json.
packages/shared/src/cli/commands/metric-views/validate-metric-views-source.test.ts	Unit tests for metric source validation + formatting.
packages/shared/src/cli/commands/metric-views/sync/sync.ts	Implements appkit mv sync (path resolution, dormancy, dynamic import, error taxonomy, interactive prompts).
packages/shared/src/cli/commands/metric-views/sync/sync.test.ts	Tests CLI behavior (flag vs interactive, error taxonomy, cache flag propagation).
packages/appkit/tsdown.config.ts	Ensures ./type-generator is built as its own entry so dynamic-import consumers see required exports.
packages/appkit/src/type-generator/index.ts	Refactors metric emission to a unified syncMetricViewsTypes pipeline and updates exported metric artifact constants.
packages/appkit/src/type-generator/mv-registry/render-types.ts	Updates comments to reflect the new artifact filename.
packages/appkit/src/type-generator/tests/vite-plugin.test.ts	Updates expected default/custom Metric View artifact filenames.
packages/appkit/src/type-generator/tests/index.test.ts	Updates expected Metric View artifact filenames in type-generator tests.
packages/appkit/src/type-generator/tests/mv-registry.test.ts	Updates metadata bundle naming references in tests.
packages/appkit/src/type-generator/tests/sync-metric-views-types.test.ts	Adds focused unit tests for the new syncMetricViewsTypes export, including cache behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pkosiec]

Reviewed the mv-cli typegen changes — solid refactor, and behavior parity for the dev/Vite (non-blocking/blocking) paths reads as preserved 1:1 (the extracted syncMetricViewsTypes keeps serveDegraded = mode !== "describe-now", the preflight, the #406 gate, the sticky-degraded notice, cache save/prune, and the fatalErrors→throw ordering). Findings inline below — mostly P3 polish; nothing blocks correctness of the extraction. Verified the --no-cache / getOptionValueSource handling and the @clack/prompts usage against their docs — both correct.

Two nits not worth their own threads:

• Stale metric.d.ts / metrics.metadata.json aren't cleaned up on the rename to metric-views.* (removeOldGeneratedTypes only removes appKitTypes.d.ts) — low impact for a pre-release feature, but an upgraded app could keep an orphaned metric.d.ts.
• The CLI's Zod pre-validation doesn't mirror resolveMetricConfig's 200-entry / 255-char-segment caps, so an over-cap config passes the "fail fast before the dynamic import" stage and throws only after it (still exit 1, just later).

Verdict: ready with minor fixes.

[calvarjorge]

maybe we should move the cli to the appkit package?

[github-actions]

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 669 KB (+6.5 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	690 KB (+879 B)	241 KB (+116 B)
Type declarations	284 KB (+16 KB)	98 KB (+6.7 KB)
Source maps	1.3 MB (+1.7 KB)	449 KB (+854 B)
Other	11 KB	3.7 KB
Total	2.3 MB (+18 KB)	791 KB (+7.6 KB)

Per-entry composition (own code — deps external (as shipped))

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	74 KB (-79 B)	2.5 KB	76 KB (-79 B)	external	243 KB (-257 B)
./beta	39 KB	231 B	39 KB	external	117 KB
./type-generator	19 KB (-25 B)	0 B	19 KB (-25 B)	external	53 KB (-131 B)

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	70 KB
.	utils.js	initial	4.0 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	30 KB
./beta	databricks.js	initial	5.7 KB
./beta	service-context.js	initial	3.0 KB
./beta	client-options.js	initial	219 B
./beta	databricks.js	lazy	128 B
./beta	index.js	lazy	103 B
./type-generator	index.js	initial	19 KB

@databricks/appkit-ui

npm tarball (packed): 297 KB — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	363 KB	120 KB
Type declarations	203 KB	73 KB
Source maps	672 KB	219 KB
CSS	16 KB	3.3 KB
Total	1.2 MB	415 KB

Per-entry composition (consumer bundle — deps bundled, peerDeps external)

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
./js	4.2 KB	49 KB	54 KB	208 KB	11 KB
./js/beta	20 B	0 B	20 B	0 B	0 B
./react	591 KB	49 KB	640 KB	1.8 MB	167 KB
./react/beta	20 B	0 B	20 B	0 B	0 B

Chunks:

Entry	Chunk	Load	Size (gz)
./js	index.js	initial	4.1 KB
./js	chunk	initial	120 B
./js	apache-arrow	lazy	49 KB
./js/beta	beta.js	initial	20 B
./react	index.js	initial	589 KB
./react	tslib	initial	2.1 KB
./react	apache-arrow	lazy	49 KB
./react/beta	beta.js	initial	20 B