@bonnard/cli 0.1.13 → 0.2.1

package/dist/bin/validate-DEh1XQnH.mjs

@@ -0,0 +1,365 @@
+import { t as getProjectPaths } from "./bon.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+
+//#region src/lib/schema.ts
+const identifier = z.string().regex(/^[_a-zA-Z][_a-zA-Z0-9]*$/, "must be a valid identifier (letters, numbers, underscores; cannot start with a number)");
+const refreshKeySchema = z.object({
+	every: z.string().regex(/^\d+\s+(second|minute|hour|day|week)s?$/, { message: "must be a time interval like \"1 hour\", \"30 minute\", \"1 day\"" }).optional(),
+	sql: z.string().optional()
+});
+const measureTypes = [
+	"count",
+	"count_distinct",
+	"count_distinct_approx",
+	"sum",
+	"avg",
+	"min",
+	"max",
+	"number",
+	"string",
+	"time",
+	"boolean",
+	"running_total",
+	"number_agg"
+];
+const dimensionTypes = [
+	"string",
+	"number",
+	"boolean",
+	"time",
+	"geo",
+	"switch"
+];
+const relationshipTypes = [
+	"many_to_one",
+	"one_to_many",
+	"one_to_one"
+];
+const granularities = [
+	"second",
+	"minute",
+	"hour",
+	"day",
+	"week",
+	"month",
+	"quarter",
+	"year"
+];
+const preAggTypes = [
+	"rollup",
+	"original_sql",
+	"rollup_join",
+	"rollup_lambda"
+];
+const formats = [
+	"percent",
+	"currency",
+	"number",
+	"imageUrl",
+	"link",
+	"id"
+];
+const measureSchema = z.object({
+	name: identifier,
+	type: z.enum(measureTypes),
+	sql: z.string().optional(),
+	description: z.string().optional(),
+	title: z.string().optional(),
+	format: z.enum(formats).optional(),
+	public: z.boolean().optional(),
+	filters: z.array(z.object({ sql: z.string() })).optional(),
+	rolling_window: z.object({
+		trailing: z.string().optional(),
+		leading: z.string().optional(),
+		offset: z.string().optional()
+	}).optional(),
+	drill_members: z.array(z.string()).optional(),
+	meta: z.record(z.string(), z.unknown()).optional()
+});
+const dimensionFormatSchema = z.union([z.enum(formats), z.string().startsWith("%")]);
+const dimensionSchema = z.object({
+	name: identifier,
+	type: z.enum(dimensionTypes),
+	sql: z.string().optional(),
+	primary_key: z.boolean().optional(),
+	sub_query: z.boolean().optional(),
+	propagate_filters_to_sub_query: z.boolean().optional(),
+	description: z.string().optional(),
+	title: z.string().optional(),
+	format: dimensionFormatSchema.optional(),
+	public: z.boolean().optional(),
+	meta: z.record(z.string(), z.unknown()).optional(),
+	latitude: z.object({ sql: z.string() }).optional(),
+	longitude: z.object({ sql: z.string() }).optional(),
+	case: z.object({
+		when: z.array(z.object({
+			sql: z.string(),
+			label: z.string()
+		})),
+		else: z.object({ label: z.string() }).optional()
+	}).optional()
+});
+const joinSchema = z.object({
+	name: identifier,
+	relationship: z.enum(relationshipTypes),
+	sql: z.string()
+});
+const segmentSchema = z.object({
+	name: identifier,
+	sql: z.string(),
+	description: z.string().optional(),
+	title: z.string().optional(),
+	public: z.boolean().optional()
+});
+const preAggregationSchema = z.object({
+	name: identifier,
+	type: z.enum(preAggTypes).optional(),
+	measures: z.array(z.string()).optional(),
+	dimensions: z.array(z.string()).optional(),
+	time_dimension: z.string().optional(),
+	granularity: z.enum(granularities).optional(),
+	partition_granularity: z.enum(granularities).optional(),
+	refresh_key: refreshKeySchema.optional(),
+	scheduled_refresh: z.boolean().optional()
+});
+const hierarchySchema = z.object({
+	name: identifier,
+	levels: z.array(z.string()),
+	title: z.string().optional(),
+	public: z.boolean().optional()
+});
+const cubeSchema = z.object({
+	name: identifier,
+	sql: z.string().optional(),
+	sql_table: z.string().optional(),
+	data_source: z.string().optional(),
+	extends: z.string().optional(),
+	description: z.string().optional(),
+	title: z.string().optional(),
+	public: z.boolean().optional(),
+	refresh_key: refreshKeySchema.optional(),
+	measures: z.array(measureSchema).optional(),
+	dimensions: z.array(dimensionSchema).optional(),
+	joins: z.array(joinSchema).optional(),
+	segments: z.array(segmentSchema).optional(),
+	pre_aggregations: z.array(preAggregationSchema).optional(),
+	hierarchies: z.array(hierarchySchema).optional()
+}).refine((data) => data.sql != null || data.sql_table != null || data.extends != null, { message: "sql, sql_table, or extends is required" });
+const viewIncludeItemSchema = z.union([z.string(), z.object({
+	name: z.string(),
+	alias: z.string().optional(),
+	title: z.string().optional(),
+	description: z.string().optional(),
+	format: z.string().optional(),
+	meta: z.record(z.string(), z.unknown()).optional()
+})]);
+const viewCubeRefSchema = z.object({
+	join_path: z.string(),
+	includes: z.union([z.literal("*"), z.array(viewIncludeItemSchema)]).optional(),
+	excludes: z.array(z.string()).optional(),
+	prefix: z.boolean().optional()
+});
+const folderSchema = z.lazy(() => z.object({
+	name: z.string(),
+	members: z.array(z.string()).optional(),
+	folders: z.array(folderSchema).optional()
+}));
+const viewMeasureSchema = z.object({
+	name: identifier,
+	sql: z.string(),
+	type: z.string(),
+	format: z.string().optional(),
+	description: z.string().optional(),
+	meta: z.record(z.string(), z.unknown()).optional()
+});
+const viewDimensionSchema = z.object({
+	name: identifier,
+	sql: z.string(),
+	type: z.string(),
+	description: z.string().optional(),
+	meta: z.record(z.string(), z.unknown()).optional()
+});
+const viewSegmentSchema = z.object({
+	name: identifier,
+	sql: z.string(),
+	description: z.string().optional()
+});
+const viewSchema = z.object({
+	name: identifier,
+	description: z.string().optional(),
+	title: z.string().optional(),
+	public: z.boolean().optional(),
+	cubes: z.array(viewCubeRefSchema).optional(),
+	measures: z.array(viewMeasureSchema).optional(),
+	dimensions: z.array(viewDimensionSchema).optional(),
+	segments: z.array(viewSegmentSchema).optional(),
+	folders: z.array(folderSchema).optional()
+});
+const fileSchema = z.object({
+	cubes: z.array(cubeSchema).optional(),
+	views: z.array(viewSchema).optional()
+}).refine((data) => data.cubes && data.cubes.length > 0 || data.views && data.views.length > 0, "File must contain at least one cube or view");
+function formatZodError(error, fileName, parsed) {
+	return error.issues.map((issue) => {
+		const pathParts = issue.path;
+		let entityContext = "";
+		if (pathParts.length >= 2) {
+			const collection = pathParts[0];
+			const index = pathParts[1];
+			const entity = parsed?.[collection]?.[index];
+			if (entity?.name) entityContext = ` (${entity.name})`;
+		}
+		const pathStr = pathParts.join(".");
+		const location = pathStr ? `${pathStr}${entityContext}` : "";
+		if (issue.code === "invalid_value" && "values" in issue) return `${fileName}: ${location} — invalid value, expected one of: ${issue.values.join(", ")}`;
+		return `${fileName}: ${location ? `${location} — ` : ""}${issue.message}`;
+	});
+}
+function validateFiles(files) {
+	const errors = [];
+	const cubes = [];
+	const views = [];
+	const allNames = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		let parsed;
+		try {
+			parsed = YAML.parse(file.content);
+		} catch (err) {
+			errors.push(`${file.fileName}: YAML parse error — ${err.message}`);
+			continue;
+		}
+		if (!parsed || typeof parsed !== "object") {
+			errors.push(`${file.fileName}: file is empty or not a YAML object`);
+			continue;
+		}
+		const result = fileSchema.safeParse(parsed);
+		if (!result.success) {
+			errors.push(...formatZodError(result.error, file.fileName, parsed));
+			continue;
+		}
+		for (const cube of parsed.cubes ?? []) if (cube.name) {
+			const existing = allNames.get(cube.name);
+			if (existing) errors.push(`${file.fileName}: duplicate name '${cube.name}' (also defined in ${existing})`);
+			else {
+				allNames.set(cube.name, file.fileName);
+				cubes.push(cube.name);
+			}
+		}
+		for (const view of parsed.views ?? []) if (view.name) {
+			const existing = allNames.get(view.name);
+			if (existing) errors.push(`${file.fileName}: duplicate name '${view.name}' (also defined in ${existing})`);
+			else {
+				allNames.set(view.name, file.fileName);
+				views.push(view.name);
+			}
+		}
+	}
+	return {
+		errors,
+		cubes,
+		views
+	};
+}
+
+//#endregion
+//#region src/lib/validate.ts
+function collectYamlFiles(dir, rootDir) {
+	if (!fs.existsSync(dir)) return [];
+	const results = [];
+	function walk(current) {
+		for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+			const fullPath = path.join(current, entry.name);
+			if (entry.isDirectory()) walk(fullPath);
+			else if (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml")) results.push({
+				fileName: path.relative(rootDir, fullPath),
+				content: fs.readFileSync(fullPath, "utf-8")
+			});
+		}
+	}
+	walk(dir);
+	return results;
+}
+function checkMissingDescriptions(files) {
+	const missing = [];
+	for (const file of files) try {
+		const parsed = YAML.parse(file.content);
+		if (!parsed) continue;
+		const cubes = parsed.cubes || [];
+		for (const cube of cubes) {
+			if (!cube.name) continue;
+			if (!cube.description) missing.push({
+				parent: cube.name,
+				type: "cube",
+				name: cube.name
+			});
+			const measures = cube.measures || [];
+			for (const measure of measures) if (measure.name && !measure.description) missing.push({
+				parent: cube.name,
+				type: "measure",
+				name: measure.name
+			});
+			const dimensions = cube.dimensions || [];
+			for (const dimension of dimensions) if (dimension.name && !dimension.description) missing.push({
+				parent: cube.name,
+				type: "dimension",
+				name: dimension.name
+			});
+		}
+		const views = parsed.views || [];
+		for (const view of views) {
+			if (!view.name) continue;
+			if (!view.description) missing.push({
+				parent: view.name,
+				type: "view",
+				name: view.name
+			});
+		}
+	} catch {}
+	return missing;
+}
+function checkMissingDataSource(files) {
+	const missing = [];
+	for (const file of files) try {
+		const parsed = YAML.parse(file.content);
+		if (!parsed) continue;
+		for (const cube of parsed.cubes || []) if (cube.name && !cube.data_source) missing.push(cube.name);
+	} catch {}
+	return missing;
+}
+async function validate(projectPath) {
+	const paths = getProjectPaths(projectPath);
+	const files = [...collectYamlFiles(paths.cubes, projectPath), ...collectYamlFiles(paths.views, projectPath)];
+	if (files.length === 0) return {
+		valid: true,
+		errors: [],
+		cubes: [],
+		views: [],
+		missingDescriptions: [],
+		cubesMissingDataSource: []
+	};
+	const result = validateFiles(files);
+	if (result.errors.length > 0) return {
+		valid: false,
+		errors: result.errors,
+		cubes: [],
+		views: [],
+		missingDescriptions: [],
+		cubesMissingDataSource: []
+	};
+	const missingDescriptions = checkMissingDescriptions(files);
+	const cubesMissingDataSource = checkMissingDataSource(files);
+	return {
+		valid: true,
+		errors: [],
+		cubes: result.cubes,
+		views: result.views,
+		missingDescriptions,
+		cubesMissingDataSource
+	};
+}
+
+//#endregion
+export { validate };

package/dist/docs/_index.md

@@ -1,6 +1,6 @@
 # Bonnard Documentation
 
-> Build semantic layers with cubes and views.
+> Learn how to build, deploy, and query a semantic layer with Bonnard. Define metrics once in YAML cubes and views, then query from any BI tool or AI agent.
 
 ## Cubes
 

package/dist/docs/topics/cubes.data-source.md

@@ -1,6 +1,6 @@
-# cubes.data-source
+# Data Source
 
-> Connect cubes to specific data warehouses.
+> The data_source property connects cubes to specific data warehouse connections. Use it when your semantic layer spans multiple databases like PostgreSQL, Snowflake, or BigQuery.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.format.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.format
+# Dimension Format
 
-> Control how dimension values are displayed.
+> The format property controls how dimension values are displayed to consumers. Apply date formatting, number formatting, or custom patterns to make dimension output human-readable.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.md

@@ -1,6 +1,6 @@
-# cubes.dimensions
+# Dimensions
 
-> Define attributes for grouping and filtering data.
+> Dimensions define the attributes used for grouping and filtering data in your semantic layer. They map to table columns and provide the axes for slicing measures in queries.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.primary-key.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.primary-key
+# Primary Key
 
-> Mark the unique identifier dimension for a cube.
+> The primary_key property marks a dimension as the unique identifier for a cube. Primary keys are required for count_distinct measures and for establishing correct join relationships.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.sub-query.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.sub-query
+# Sub-Query Dimensions
 
-> Bring measures from other cubes into a dimension.
+> Sub-query dimensions let you bring a measure from another cube into a dimension using a correlated subquery. Useful for denormalizing aggregated values like "lifetime revenue per user."
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.time.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.time
+# Time Dimensions
 
-> Enable time-based analysis with time dimensions.
+> Time dimensions enable date and time-based analysis in your semantic layer. They support automatic granularity (day, week, month, year) and power time-series queries and date filters.
 
 ## Overview
 

package/dist/docs/topics/cubes.dimensions.types.md

@@ -1,6 +1,6 @@
-# cubes.dimensions.types
+# Dimension Types
 
-> The 6 dimension types for categorizing and filtering data.
+> Reference for all 6 dimension types in Bonnard: string, number, boolean, time, geo, and json. Each type determines how the dimension is stored, indexed, and queried.
 
 ## Overview
 

package/dist/docs/topics/cubes.extends.md

@@ -1,6 +1,6 @@
-# cubes.extends
+# Extends
 
-> Reuse members from other cubes to reduce duplication.
+> Extends lets you inherit measures, dimensions, and joins from other cubes to reduce duplication. Build base cubes with shared logic and extend them for specific use cases.
 
 ## Overview
 

package/dist/docs/topics/cubes.hierarchies.md

@@ -1,6 +1,6 @@
-# cubes.hierarchies
+# Hierarchies
 
-> Define drill-down paths for dimensional analysis.
+> Hierarchies define drill-down paths for dimensional analysis in your semantic layer. Set up parent-child relationships between dimensions so consumers can explore data at different levels.
 
 ## Overview
 

package/dist/docs/topics/cubes.joins.md

@@ -1,6 +1,6 @@
-# cubes.joins
+# Joins
 
-> Connect cubes together to enable cross-cube analysis.
+> Joins connect cubes together so you can query measures and dimensions across multiple tables. Define one-to-many, many-to-one, and one-to-one relationships between cubes.
 
 ## Overview
 

package/dist/docs/topics/cubes.md

@@ -1,6 +1,6 @@
-# cubes
+# Cubes
 
-> Define cubes that map to your database tables.
+> Cubes are the core building blocks of a Bonnard semantic layer. Each cube maps to a database table and defines the measures, dimensions, and joins available for querying.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.calculated.md

@@ -1,6 +1,6 @@
-# cubes.measures.calculated
+# Calculated Measures
 
-> Build complex metrics from other measures.
+> Calculated measures let you build complex metrics from other measures in the same cube. Combine existing aggregations to create ratios, percentages, and derived metrics without raw SQL.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.drill-members.md

@@ -1,6 +1,6 @@
-# cubes.measures.drill-members
+# Drill Members
 
-> Define which dimensions to show when drilling into a measure.
+> Drill members define which dimensions are shown when a user drills into a measure. Configure drill-down paths so consumers can explore aggregated numbers down to individual records.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.filters.md

@@ -1,6 +1,6 @@
-# cubes.measures.filters
+# Measure Filters
 
-> Apply permanent filters to measures for conditional aggregations.
+> Measure filters apply permanent WHERE conditions to measures for conditional aggregations. Create filtered metrics like "revenue from paid plans" or "active users in the last 30 days."
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.format.md

@@ -1,6 +1,6 @@
-# cubes.measures.format
+# Measure Format
 
-> Specify how measure values should be displayed.
+> The format property controls how measure values are displayed to consumers. Specify currency symbols, decimal places, percentage formatting, and custom number patterns.
 
 ## Overview
 
@@ -27,6 +27,12 @@ measures:
 
 ## Supported Formats
 
+| Format | Description |
+|--------|-------------|
+| `percent` | Percentage display (0.75 → 75%) |
+| `currency` | Monetary display ($1,234.56) |
+| `number` | Plain number with standard formatting |
+
 ### percent
 
 Displays value as a percentage:
@@ -53,6 +59,19 @@ Displays value as monetary amount:
 
 Output: `$1,234.56` (formatting depends on BI tool locale)
 
+### number
+
+Standard number formatting with grouping separators:
+
+```yaml
+- name: total_slots
+  type: sum
+  sql: slot_count
+  format: number
+```
+
+Output: `1,234` instead of raw `1234`. Use this when the measure represents a count or quantity that benefits from thousand separators.
+
 ## Usage Notes
 
 ### Format vs Calculation

package/dist/docs/topics/cubes.measures.md

@@ -1,6 +1,6 @@
-# cubes.measures
+# Measures
 
-> Define metrics and aggregations for analytical queries.
+> Measures define the metrics and aggregations in your semantic layer. Use them to calculate sums, counts, averages, and custom expressions that stay consistent across every consumer.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.rolling.md

@@ -1,6 +1,6 @@
-# cubes.measures.rolling
+# Rolling Measures
 
-> Calculate rolling window aggregations (7-day average, 30-day sum, etc).
+> Rolling measures calculate aggregations over sliding time windows like 7-day averages, 30-day sums, and month-to-date totals. Define the window type, trailing period, and offset.
 
 ## Overview
 

package/dist/docs/topics/cubes.measures.types.md

@@ -1,6 +1,6 @@
-# cubes.measures.types
+# Measure Types
 
-> The 12 measure types available for aggregating data.
+> Reference for all 12 measure types available in Bonnard: count, sum, avg, min, max, count_distinct, running_total, and more. Each type maps to a specific SQL aggregation.
 
 ## Overview
 

package/dist/docs/topics/cubes.public.md

@@ -1,6 +1,6 @@
-# cubes.public
+# Public
 
-> Control visibility of cubes, measures, and dimensions in the API.
+> The public property controls whether cubes, measures, and dimensions are exposed in the API. Set public to false to hide internal implementation details from consumers.
 
 ## Overview
 

package/dist/docs/topics/cubes.refresh-key.md

@@ -1,6 +1,6 @@
-# cubes.refresh-key
+# Refresh Key
 
-> Control when cube data is refreshed in the cache.
+> The refresh_key property controls when cube data is refreshed in the cache. Define time-based or query-based refresh strategies to balance data freshness with query performance.
 
 ## Overview
 

package/dist/docs/topics/cubes.segments.md

@@ -1,6 +1,6 @@
-# cubes.segments
+# Segments
 
-> Define reusable row-level filters.
+> Segments define reusable row-level filters that can be applied to any query on a cube. Use them for common filters like "active users" or "paid orders" that multiple consumers need.
 
 ## Overview
 

package/dist/docs/topics/cubes.sql.md

@@ -1,6 +1,6 @@
-# cubes.sql
+# SQL
 
-> Define the SQL table or subquery that powers a cube.
+> Define the SQL table or subquery that powers a cube. Use the sql property to point to a physical table, or write a SELECT statement for derived datasets and transformations.
 
 ## Overview
 

package/dist/docs/topics/features.catalog.md

@@ -0,0 +1,31 @@
+# Catalog
+
+> Browse and understand your data model — no code required.
+
+The Bonnard catalog gives everyone on your team a live view of your semantic layer. Browse cubes, views, measures, and dimensions from the browser. Understand what data is available before writing a single query.
+
+## What you can explore
+
+- **Cubes and Views** — See every deployed source with field counts at a glance
+- **Measures** — Aggregation type, SQL expression, format (currency, percentage), and description
+- **Dimensions** — Data type, time granularity options, and custom metadata
+- **Segments** — Pre-defined filters available for queries
+
+## Field-level detail
+
+Click any field to see exactly how it's calculated:
+
+- **SQL expression** — The underlying query logic
+- **Type and format** — How the field is aggregated and displayed
+- **Origin cube** — Which cube a view field traces back to
+- **Referenced fields** — Dependencies this field relies on
+- **Custom metadata** — Tags, labels, and annotations set by your data team
+
+## Built for business users
+
+The catalog is designed for anyone who needs to understand the data, not just engineers. No YAML, no terminal, no warehouse credentials. Browse the schema, read descriptions, and know exactly what to ask your AI agent for.
+
+## See Also
+
+- [views](views) — How to create curated views for your team
+- [cubes.public](cubes.public) — Control which cubes are visible