@databricks/appkit 0.1.5 → 0.2.0

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

@@ -1,8 +1,10 @@
+import { createLogger } from "../logging/logger.js";
 import { generateFromEntryPoint } from "./index.js";
 import path from "node:path";
 import fs from "node:fs";
 
 //#region src/type-generator/vite-plugin.ts
+const logger = createLogger("type-generator:vite-plugin");
 /**
 * Vite plugin to generate types for AppKit queries.
 * Calls generateFromEntryPoint under the hood.
@@ -17,7 +19,7 @@ function appKitTypesPlugin(options) {
 		try {
 			const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || "";
 			if (!warehouseId) {
-				console.warn("[AppKit] Warehouse ID not found. Skipping type generation.");
+				logger.debug("Warehouse ID not found. Skipping type generation.");
 				return;
 			}
 			await generateFromEntryPoint({
@@ -28,14 +30,14 @@ function appKitTypesPlugin(options) {
 			});
 		} catch (error) {
 			if (process.env.NODE_ENV === "production") throw error;
-			console.error("[AppKit] Error generating types:", error);
+			logger.error("Error generating types: %O", error);
 		}
 	}
 	return {
 		name: "appkit-types",
 		apply() {
 			if (!(process.env.DATABRICKS_WAREHOUSE_ID || "")) {
-				console.warn("[AppKit] Warehouse ID not found. Skipping type generation.");
+				logger.debug("Warehouse ID not found. Skipping type generation.");
 				return false;
 			}
 			if (!fs.existsSync(path.join(process.cwd(), "config", "queries"))) return false;

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 path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport fs from \"node:fs\";\nimport { generateFromEntryPoint } from \"./index\";\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 root: string;\n  let outFile: string;\n  let watchFolders: string[];\n\n  async function generate() {\n    try {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        console.warn(\n          \"[AppKit] Warehouse ID not found. Skipping type generation.\",\n        );\n        return;\n      }\n\n      await generateFromEntryPoint({\n        outFile,\n        queryFolder: watchFolders[0],\n        warehouseId,\n        noCache: false,\n      });\n    } catch (error) {\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        throw error;\n      }\n      console.error(\"[AppKit] Error generating types:\", error);\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        console.warn(\n          \"[AppKit] Warehouse ID not found. Skipping type generation.\",\n        );\n        return false;\n      }\n\n      if (!fs.existsSync(path.join(process.cwd(), \"config\", \"queries\"))) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      root = config.root;\n      outFile = path.resolve(root, options?.outFile ?? \"src/appKitTypes.d.ts\");\n      watchFolders = options?.watchFolders ?? [\n        path.join(process.cwd(), \"config\", \"queries\"),\n      ];\n    },\n\n    buildStart() {\n      generate();\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          generate();\n        }\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;AAqBA,SAAgB,kBAAkB,SAA4C;CAC5E,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,eAAe,WAAW;AACxB,MAAI;GACF,MAAM,cAAc,QAAQ,IAAI,2BAA2B;AAE3D,OAAI,CAAC,aAAa;AAChB,YAAQ,KACN,6DACD;AACD;;AAGF,SAAM,uBAAuB;IAC3B;IACA,aAAa,aAAa;IAC1B;IACA,SAAS;IACV,CAAC;WACK,OAAO;AAEd,OAAI,QAAQ,IAAI,aAAa,aAC3B,OAAM;AAER,WAAQ,MAAM,oCAAoC,MAAM;;;AAI5D,QAAO;EACL,MAAM;EAEN,QAAQ;AAGN,OAAI,EAFgB,QAAQ,IAAI,2BAA2B,KAEzC;AAChB,YAAQ,KACN,6DACD;AACD,WAAO;;AAGT,OAAI,CAAC,GAAG,WAAW,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAAC,CAC/D,QAAO;AAGT,UAAO;;EAGT,eAAe,QAAQ;AACrB,UAAO,OAAO;AACd,aAAU,KAAK,QAAQ,MAAM,SAAS,WAAW,uBAAuB;AACxE,kBAAe,SAAS,gBAAgB,CACtC,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAC9C;;EAGH,aAAa;AACX,aAAU;;EAGZ,gBAAgB,QAAQ;AACtB,UAAO,QAAQ,IAAI,aAAa;AAEhC,UAAO,QAAQ,GAAG,WAAW,gBAAgB;AAK3C,QAJsB,aAAa,MAAM,WACvC,YAAY,WAAW,OAAO,CAC/B,IAEoB,YAAY,SAAS,OAAO,CAC/C,WAAU;KAEZ;;EAEL"}
+{"version":3,"file":"vite-plugin.js","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport { createLogger } from \"../logging/logger\";\nimport { generateFromEntryPoint } from \"./index\";\n\nconst logger = createLogger(\"type-generator:vite-plugin\");\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 root: string;\n  let outFile: string;\n  let watchFolders: string[];\n\n  async function generate() {\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      });\n    } catch (error) {\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        throw error;\n      }\n      logger.error(\"Error generating types: %O\", error);\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 (!fs.existsSync(path.join(process.cwd(), \"config\", \"queries\"))) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      root = config.root;\n      outFile = path.resolve(root, options?.outFile ?? \"src/appKitTypes.d.ts\");\n      watchFolders = options?.watchFolders ?? [\n        path.join(process.cwd(), \"config\", \"queries\"),\n      ];\n    },\n\n    buildStart() {\n      generate();\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          generate();\n        }\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;AAMA,MAAM,SAAS,aAAa,6BAA6B;;;;;;;AAkBzD,SAAgB,kBAAkB,SAA4C;CAC5E,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,eAAe,WAAW;AACxB,MAAI;GACF,MAAM,cAAc,QAAQ,IAAI,2BAA2B;AAE3D,OAAI,CAAC,aAAa;AAChB,WAAO,MAAM,oDAAoD;AACjE;;AAGF,SAAM,uBAAuB;IAC3B;IACA,aAAa,aAAa;IAC1B;IACA,SAAS;IACV,CAAC;WACK,OAAO;AAEd,OAAI,QAAQ,IAAI,aAAa,aAC3B,OAAM;AAER,UAAO,MAAM,8BAA8B,MAAM;;;AAIrD,QAAO;EACL,MAAM;EAEN,QAAQ;AAGN,OAAI,EAFgB,QAAQ,IAAI,2BAA2B,KAEzC;AAChB,WAAO,MAAM,oDAAoD;AACjE,WAAO;;AAGT,OAAI,CAAC,GAAG,WAAW,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAAC,CAC/D,QAAO;AAGT,UAAO;;EAGT,eAAe,QAAQ;AACrB,UAAO,OAAO;AACd,aAAU,KAAK,QAAQ,MAAM,SAAS,WAAW,uBAAuB;AACxE,kBAAe,SAAS,gBAAgB,CACtC,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAC9C;;EAGH,aAAa;AACX,aAAU;;EAGZ,gBAAgB,QAAQ;AACtB,UAAO,QAAQ,IAAI,aAAa;AAEhC,UAAO,QAAQ,GAAG,WAAW,gBAAgB;AAK3C,QAJsB,aAAa,MAAM,WACvC,YAAY,WAAW,OAAO,CAC/B,IAEoB,YAAY,SAAS,OAAO,CAC/C,WAAU;KAEZ;;EAEL"}

package/dist/utils/env-validator.js

@@ -1,8 +1,12 @@
+import { ValidationError } from "../errors/validation.js";
+import { init_errors } from "../errors/index.js";
+
 //#region src/utils/env-validator.ts
+init_errors();
 function validateEnv(envVars) {
 	const missingVars = [];
 	for (const envVar of envVars) if (!process.env[envVar]) missingVars.push(envVar);
-	if (missingVars.length > 0) throw new Error(`Missing required environment variables: ${missingVars.join(", ")}`);
+	if (missingVars.length > 0) throw ValidationError.missingEnvVars(missingVars);
 }
 
 //#endregion

package/dist/utils/env-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-validator.js","names":[],"sources":["../../src/utils/env-validator.ts"],"sourcesContent":["export function validateEnv(envVars: string[]) {\n  const missingVars = [];\n\n  for (const envVar of envVars) {\n    if (!process.env[envVar]) {\n      missingVars.push(envVar);\n    }\n  }\n\n  if (missingVars.length > 0) {\n    throw new Error(\n      `Missing required environment variables: ${missingVars.join(\", \")}`,\n    );\n  }\n}\n"],"mappings":";AAAA,SAAgB,YAAY,SAAmB;CAC7C,MAAM,cAAc,EAAE;AAEtB,MAAK,MAAM,UAAU,QACnB,KAAI,CAAC,QAAQ,IAAI,QACf,aAAY,KAAK,OAAO;AAI5B,KAAI,YAAY,SAAS,EACvB,OAAM,IAAI,MACR,2CAA2C,YAAY,KAAK,KAAK,GAClE"}
+{"version":3,"file":"env-validator.js","names":[],"sources":["../../src/utils/env-validator.ts"],"sourcesContent":["import { ValidationError } from \"../errors\";\n\nexport function validateEnv(envVars: string[]) {\n  const missingVars = [];\n\n  for (const envVar of envVars) {\n    if (!process.env[envVar]) {\n      missingVars.push(envVar);\n    }\n  }\n\n  if (missingVars.length > 0) {\n    throw ValidationError.missingEnvVars(missingVars);\n  }\n}\n"],"mappings":";;;;aAA4C;AAE5C,SAAgB,YAAY,SAAmB;CAC7C,MAAM,cAAc,EAAE;AAEtB,MAAK,MAAM,UAAU,QACnB,KAAI,CAAC,QAAQ,IAAI,QACf,aAAY,KAAK,OAAO;AAI5B,KAAI,YAAY,SAAS,EACvB,OAAM,gBAAgB,eAAe,YAAY"}

package/dist/utils/path-exclusions.js

@@ -0,0 +1,66 @@
+//#region src/utils/path-exclusions.ts
+/**
+* Paths and patterns to exclude from tracing and logging.
+* Requests matching these will not create spans or WideEvents.
+*/
+const EXCLUDED_PATH_PREFIXES = [
+	"/@fs/",
+	"/@vite/",
+	"/@id/",
+	"/@react-refresh",
+	"/src/",
+	"/node_modules/",
+	"/favicon.ico",
+	"/_next/",
+	"/static/",
+	"/health",
+	"/metrics"
+];
+/**
+* File extensions to exclude from tracing.
+* These are typically static assets that don't need tracing.
+*/
+const EXCLUDED_EXTENSIONS = [
+	".svg",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".ico",
+	".css",
+	".woff",
+	".woff2",
+	".ttf",
+	".eot",
+	".map",
+	".js"
+];
+/**
+* Check if a request should be ignored for tracing.
+* This is the primary filter used by HttpInstrumentation.
+*/
+function shouldIgnoreRequest(request) {
+	const url = request.url;
+	if (!url) return false;
+	const path = url.split("?")[0];
+	return shouldExcludePath(path);
+}
+/**
+* Check if a path should be excluded from tracing/logging.
+* Returns true if path should be excluded, false otherwise.
+*/
+function shouldExcludePath(path) {
+	if (typeof path !== "string") return false;
+	const cleanPath = path.split("?")[0];
+	const lowerPath = cleanPath.toLowerCase();
+	for (const prefix of EXCLUDED_PATH_PREFIXES) if (cleanPath.includes(prefix)) return true;
+	if (!cleanPath.startsWith("/api/")) {
+		for (const ext of EXCLUDED_EXTENSIONS) if (lowerPath.endsWith(ext)) return true;
+	}
+	return false;
+}
+
+//#endregion
+export { shouldExcludePath, shouldIgnoreRequest };
+//# sourceMappingURL=path-exclusions.js.map

package/dist/utils/path-exclusions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-exclusions.js","names":[],"sources":["../../src/utils/path-exclusions.ts"],"sourcesContent":["import type { IncomingMessage } from \"node:http\";\n\n/**\n * Paths and patterns to exclude from tracing and logging.\n * Requests matching these will not create spans or WideEvents.\n */\nexport const EXCLUDED_PATH_PREFIXES = [\n  // Vite dev server internals\n  \"/@fs/\",\n  \"/@vite/\",\n  \"/@id/\",\n  \"/@react-refresh\",\n  \"/src/\", // Vite HMR source files\n  \"/node_modules/\",\n\n  // Static assets and common paths\n  \"/favicon.ico\",\n  \"/_next/\",\n  \"/static/\",\n\n  // Health checks\n  \"/health\",\n  \"/metrics\",\n];\n\n/**\n * File extensions to exclude from tracing.\n * These are typically static assets that don't need tracing.\n */\nexport const EXCLUDED_EXTENSIONS = [\n  \".svg\",\n  \".png\",\n  \".jpg\",\n  \".jpeg\",\n  \".gif\",\n  \".webp\",\n  \".ico\",\n  \".css\",\n  \".woff\",\n  \".woff2\",\n  \".ttf\",\n  \".eot\",\n  \".map\", // Source maps\n  \".js\", // Static JS files (not API endpoints)\n];\n\n/**\n * Check if a request should be ignored for tracing.\n * This is the primary filter used by HttpInstrumentation.\n */\nexport function shouldIgnoreRequest(request: IncomingMessage): boolean {\n  const url = request.url;\n  if (!url) return false;\n\n  // Remove query string for path matching\n  const path = url.split(\"?\")[0];\n\n  return shouldExcludePath(path);\n}\n\n/**\n * Check if a path should be excluded from tracing/logging.\n * Returns true if path should be excluded, false otherwise.\n */\nexport function shouldExcludePath(path: string | undefined): boolean {\n  if (typeof path !== \"string\") return false;\n\n  // Remove query string\n  const cleanPath = path.split(\"?\")[0];\n  const lowerPath = cleanPath.toLowerCase();\n\n  // Check path prefixes\n  for (const prefix of EXCLUDED_PATH_PREFIXES) {\n    if (cleanPath.includes(prefix)) {\n      return true;\n    }\n  }\n\n  // Check file extensions (but not for /api/ routes)\n  if (!cleanPath.startsWith(\"/api/\")) {\n    for (const ext of EXCLUDED_EXTENSIONS) {\n      if (lowerPath.endsWith(ext)) {\n        return true;\n      }\n    }\n  }\n\n  return false;\n}\n"],"mappings":";;;;;AAMA,MAAa,yBAAyB;CAEpC;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CACD;;;;;AAMD,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;AAMD,SAAgB,oBAAoB,SAAmC;CACrE,MAAM,MAAM,QAAQ;AACpB,KAAI,CAAC,IAAK,QAAO;CAGjB,MAAM,OAAO,IAAI,MAAM,IAAI,CAAC;AAE5B,QAAO,kBAAkB,KAAK;;;;;;AAOhC,SAAgB,kBAAkB,MAAmC;AACnE,KAAI,OAAO,SAAS,SAAU,QAAO;CAGrC,MAAM,YAAY,KAAK,MAAM,IAAI,CAAC;CAClC,MAAM,YAAY,UAAU,aAAa;AAGzC,MAAK,MAAM,UAAU,uBACnB,KAAI,UAAU,SAAS,OAAO,CAC5B,QAAO;AAKX,KAAI,CAAC,UAAU,WAAW,QAAQ,EAChC;OAAK,MAAM,OAAO,oBAChB,KAAI,UAAU,SAAS,IAAI,CACzB,QAAO;;AAKb,QAAO"}

package/llms.txt

@@ -668,6 +668,56 @@ export function SpendChart() {
 }
 ```
 
+**Chart props reference (important):**
+
+Charts are **self-contained ECharts components**. Configure via props, NOT children:
+
+```tsx
+// ✅ Correct: use props for customization
+<BarChart
+  queryKey="sales_by_region"
+  parameters={{}}
+  xKey="region"                    // X-axis field
+  yKey={["revenue", "expenses"]}   // Y-axis field(s) - string or string[]
+  colors={['#40d1f5', '#4462c9']}  // Custom colors
+  stacked                          // Stack bars (BarChart, AreaChart)
+  orientation="horizontal"         // "vertical" (default) | "horizontal"
+  showLegend                       // Show legend
+  height={400}                     // Height in pixels (default: 300)
+/>
+
+<LineChart
+  queryKey="trend_data"
+  parameters={{}}
+  xKey="date"
+  yKey="value"
+  smooth                           // Smooth curves (default: true)
+  showSymbol={false}               // Hide data point markers
+/>
+```
+
+**❌ CRITICAL: Charts do NOT accept Recharts children**
+
+```tsx
+// ❌ WRONG - AppKit charts are NOT Recharts wrappers
+import { BarChart } from "@databricks/appkit-ui/react";
+import { Bar, XAxis, YAxis, CartesianGrid } from "recharts";
+
+<BarChart queryKey="data" parameters={{}}>
+  <CartesianGrid />  // ❌ This will cause TypeScript errors
+  <XAxis dataKey="x" />  // ❌ Not supported
+  <Bar dataKey="y" />  // ❌ Not supported
+</BarChart>
+
+// ✅ CORRECT - use props instead
+<BarChart
+  queryKey="data"
+  parameters={{}}
+  xKey="x"
+  yKey="y"
+/>
+```
+
 ### SQL helpers (`sql.*`)
 
 Use these to build typed parameters (they return marker objects: `{ __sql_type, value }`):
@@ -1169,6 +1219,7 @@ env:
   - `useMemo` wraps parameters objects
   - Loading/error/empty states are explicit
   - Charts use `format="auto"` unless you have a reason to force `"json"`/`"arrow"`
+  - Charts use props (`xKey`, `yKey`, `colors`) NOT children (they're ECharts-based, not Recharts)
   - If using tooltips: root is wrapped with `<TooltipProvider>`
 
 - **Never**
@@ -1176,4 +1227,5 @@ env:
   - Don't pass untyped raw params for annotated queries
   - Don't ignore `createApp()`'s promise
   - Don't invent UI components not listed in this file
+  - Don't pass Recharts children (`<Bar>`, `<XAxis>`, etc.) to AppKit chart components
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "packageManager": "pnpm@10.21.0",
@@ -26,6 +26,7 @@
   },
   "bin": {
     "appkit-generate-types": "./bin/generate-types.js",
+    "appkit-lint": "./bin/appkit-lint.js",
     "appkit-setup": "./bin/setup-claude.js"
   },
   "scripts": {
@@ -39,6 +40,7 @@
     "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
+    "@ast-grep/napi": "^0.37.0",
     "@databricks/sdk-experimental": "^0.15.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.208.0",
@@ -57,6 +59,7 @@
     "@types/semver": "^7.7.1",
     "dotenv": "^16.6.1",
     "express": "^4.22.0",
+    "obug": "^2.1.1",
     "pg": "^8.16.3",
     "semver": "^7.7.3",
     "vite": "npm:rolldown-vite@7.1.14",