@bonnard/cli 0.1.3 → 0.1.5

package/dist/bin/models-IsV2sX74.mjs

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+
+//#region src/lib/models/datasources.ts
+/**
+* Extract datasource references from Cube model files
+*/
+/**
+* Collect all YAML files from a directory recursively
+*/
+function collectYamlFiles(dir) {
+	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(fullPath);
+		}
+	}
+	walk(dir);
+	return results;
+}
+/**
+* Parse a single model file and extract datasource references
+*/
+function extractFromFile(filePath) {
+	const datasourceToCubes = /* @__PURE__ */ new Map();
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		const parsed = YAML.parse(content);
+		if (!parsed) return datasourceToCubes;
+		if (parsed.cubes) for (const cube of parsed.cubes) {
+			const ds = cube.data_source || "default";
+			const existing = datasourceToCubes.get(ds) || [];
+			existing.push(cube.name);
+			datasourceToCubes.set(ds, existing);
+		}
+		if (parsed.views) {
+			for (const view of parsed.views) if (view.data_source) {
+				const existing = datasourceToCubes.get(view.data_source) || [];
+				existing.push(view.name);
+				datasourceToCubes.set(view.data_source, existing);
+			}
+		}
+	} catch {}
+	return datasourceToCubes;
+}
+/**
+* Extract all unique datasource references from models/ and views/ directories
+* Returns datasource names mapped to the cubes that use them
+*/
+function extractDatasourcesFromModels(projectPath) {
+	const modelsDir = path.join(projectPath, "models");
+	const viewsDir = path.join(projectPath, "views");
+	const allFiles = [...collectYamlFiles(modelsDir), ...collectYamlFiles(viewsDir)];
+	const aggregated = /* @__PURE__ */ new Map();
+	for (const file of allFiles) {
+		const fileRefs = extractFromFile(file);
+		for (const [ds, cubes] of fileRefs) {
+			const existing = aggregated.get(ds) || [];
+			existing.push(...cubes);
+			aggregated.set(ds, existing);
+		}
+	}
+	const results = [];
+	for (const [name, cubes] of aggregated) if (name !== "default") results.push({
+		name,
+		cubes
+	});
+	return results;
+}
+
+//#endregion
+export { extractDatasourcesFromModels };

package/dist/bin/{validate-Bd1D39Bj.mjs → validate-C4EHvJzJ.mjs}

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import YAML from "yaml";
 import { compile } from "@cubejs-backend/schema-compiler";
 
 //#region src/lib/validate.ts
@@ -19,6 +20,44 @@ function collectYamlFiles(dir, rootDir) {
 	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 createModelRepository(projectPath) {
 	const modelsDir = path.join(projectPath, "models");
 	const viewsDir = path.join(projectPath, "views");
@@ -32,11 +71,13 @@ function createModelRepository(projectPath) {
 }
 async function validate(projectPath) {
 	const repo = createModelRepository(projectPath);
-	if ((await repo.dataSchemaFiles()).length === 0) return {
+	const files = await repo.dataSchemaFiles();
+	if (files.length === 0) return {
 		valid: true,
 		errors: [],
 		cubes: [],
-		views: []
+		views: [],
+		missingDescriptions: []
 	};
 	try {
 		const { cubeEvaluator } = await compile(repo, {});
@@ -48,7 +89,8 @@ async function validate(projectPath) {
 			valid: true,
 			errors: [],
 			cubes,
-			views
+			views,
+			missingDescriptions: checkMissingDescriptions(files)
 		};
 	} catch (err) {
 		const raw = err.messages ?? err.message ?? String(err);
@@ -56,7 +98,8 @@ async function validate(projectPath) {
 			valid: false,
 			errors: Array.isArray(raw) ? raw : [raw],
 			cubes: [],
-			views: []
+			views: [],
+			missingDescriptions: []
 		};
 	}
 }

package/dist/docs/README.md

@@ -0,0 +1,78 @@
+# Bonnard CLI Documentation
+
+This directory contains the documentation served by `bon docs`.
+
+## Structure
+
+```
+docs/
+├── _index.md           # Index shown by `bon docs` (llms.txt style)
+├── topics/             # Individual topic files
+│   ├── cubes.md
+│   ├── cubes.measures.md
+│   ├── cubes.measures.types.md
+│   └── ...
+├── schemas/            # JSON schemas for validation
+│   ├── cube.schema.json
+│   └── view.schema.json
+└── README.md           # This file
+```
+
+## Topic Naming Convention
+
+Topic IDs use dot notation that maps directly to filenames:
+
+| Topic ID | File |
+|----------|------|
+| `cubes` | `topics/cubes.md` |
+| `cubes.measures` | `topics/cubes.measures.md` |
+| `cubes.measures.types` | `topics/cubes.measures.types.md` |
+
+## Topic File Format
+
+Each topic file should follow this structure:
+
+```markdown
+# topic.name
+
+> Brief one-line description.
+
+## Overview
+
+Short explanation (2-3 sentences).
+
+## Example
+
+```yaml
+# Minimal working example
+```
+
+## Reference
+
+| Property | Type | Description |
+|----------|------|-------------|
+| name | string | ... |
+
+## See Also
+
+- related.topic
+- another.topic
+
+```
+
+## Guidelines
+
+- Keep topics concise (~20-40 lines)
+- Lead with examples, not theory
+- Use tables for property references
+- Include "See Also" for discoverability
+
+## Commands
+
+```bash
+bon docs                    # Show index
+bon docs <topic>            # Show specific topic
+bon docs <topic> --recursive # Show topic + children
+bon docs --search <query>   # Search topics
+bon docs schema <type>      # Show JSON schema
+```

package/dist/docs/_index.md

@@ -0,0 +1,70 @@
+# Bonnard Documentation
+
+> Build semantic layers with Cube models and views.
+
+## Cubes
+
+### Core
+- [cubes](cubes) - Define data models with measures and dimensions
+- [cubes.sql](cubes.sql) - Base SQL table or query
+- [cubes.extends](cubes.extends) - Reuse members from other cubes
+- [cubes.public](cubes.public) - Control API visibility
+- [cubes.refresh-key](cubes.refresh-key) - Cache invalidation strategies
+- [cubes.data-source](cubes.data-source) - Connect cubes to warehouses
+
+### Measures
+- [cubes.measures](cubes.measures) - Quantitative metrics (count, sum, avg)
+- [cubes.measures.types](cubes.measures.types) - All 12 measure types
+- [cubes.measures.filters](cubes.measures.filters) - Measure-level filters
+- [cubes.measures.calculated](cubes.measures.calculated) - Derived metrics from other measures
+- [cubes.measures.rolling](cubes.measures.rolling) - Rolling window aggregations
+- [cubes.measures.drill-members](cubes.measures.drill-members) - Drill-down dimensions
+- [cubes.measures.format](cubes.measures.format) - Output formatting (percent, currency)
+
+### Dimensions
+- [cubes.dimensions](cubes.dimensions) - Attributes for grouping/filtering
+- [cubes.dimensions.types](cubes.dimensions.types) - All 6 dimension types
+- [cubes.dimensions.primary-key](cubes.dimensions.primary-key) - Unique identifiers for joins
+- [cubes.dimensions.time](cubes.dimensions.time) - Time-based analysis
+- [cubes.dimensions.sub-query](cubes.dimensions.sub-query) - Bring measures into dimensions
+- [cubes.dimensions.format](cubes.dimensions.format) - Display formatting (link, image, etc.)
+
+### Relationships & Filters
+- [cubes.joins](cubes.joins) - Relationships between cubes
+- [cubes.hierarchies](cubes.hierarchies) - Drill-down paths for analysis
+- [cubes.segments](cubes.segments) - Reusable predefined filters
+
+## Views
+
+- [views](views) - Compose cubes into focused interfaces
+- [views.cubes](views.cubes) - Include cubes with join paths
+- [views.includes](views.includes) - Select members to expose
+- [views.folders](views.folders) - Organize members into groups
+
+## Pre-Aggregations
+
+- [pre-aggregations](pre-aggregations) - Materialize query results for performance
+- [pre-aggregations.rollup](pre-aggregations.rollup) - Summarized data tables
+
+## Syntax
+
+- [syntax](syntax) - YAML syntax and conventions
+- [syntax.references](syntax.references) - Reference columns, members, and cubes
+- [syntax.context-variables](syntax.context-variables) - CUBE, FILTER_PARAMS, COMPILE_CONTEXT
+
+## Workflow
+
+- [workflow](workflow) - End-to-end development workflow
+- [workflow.validate](workflow.validate) - Validate models locally
+- [workflow.deploy](workflow.deploy) - Deploy to Bonnard
+- [workflow.query](workflow.query) - Query the deployed semantic layer
+- [workflow.mcp](workflow.mcp) - Connect AI agents via MCP
+
+## Quick Reference
+
+```bash
+bon docs <topic>            # View topic
+bon docs <topic> --recursive # View topic + children
+bon docs --search <query>   # Search all topics
+bon docs schema <type>      # JSON schema for validation
+```

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

@@ -0,0 +1,92 @@
+# cubes.data-source
+
+> Connect cubes to specific data warehouses.
+
+## Overview
+
+The `data_source` property specifies which configured data source a cube should use. This enables multi-database architectures where different cubes query different warehouses.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+    data_source: default
+
+  - name: analytics_events
+    sql_table: events
+    data_source: clickhouse_analytics
+```
+
+## Syntax
+
+### Single Data Source
+
+```yaml
+cubes:
+  - name: users
+    sql_table: users
+    data_source: postgres_main
+```
+
+### Default Behavior
+
+If `data_source` is omitted, the cube uses the `default` data source:
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: orders
+    # Uses "default" data source
+```
+
+## Multi-Database Architecture
+
+Different cubes can query different databases:
+
+```yaml
+cubes:
+  # Transactional data from Postgres
+  - name: orders
+    sql_table: public.orders
+    data_source: postgres
+
+  # Analytics events from ClickHouse
+  - name: events
+    sql_table: analytics.events
+    data_source: clickhouse
+
+  # ML features from Snowflake
+  - name: predictions
+    sql_table: ml.predictions
+    data_source: snowflake
+```
+
+## Data Source Configuration
+
+Data sources are configured in your Bonnard project:
+
+```yaml
+# .bon/datasources.yaml
+datasources:
+  - name: default
+    type: postgres
+    host: localhost
+    database: mydb
+
+  - name: analytics
+    type: snowflake
+    account: myaccount
+    database: ANALYTICS
+```
+
+## Cross-Database Joins
+
+Cubes from different data sources cannot be directly joined. Use views or pre-aggregations to combine data from multiple sources.
+
+## See Also
+
+- cubes
+- cubes.sql
+- workflow.deploy

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

@@ -0,0 +1,195 @@
+# cubes.dimensions.format
+
+> Control how dimension values are displayed.
+
+## Overview
+
+The `format` property hints to BI tools how to render dimension values. Dimensions support more format options than measures.
+
+## Example
+
+```yaml
+dimensions:
+  - name: avatar_url
+    type: string
+    sql: avatar_url
+    format: imageUrl
+
+  - name: profile_link
+    type: string
+    sql: "CONCAT('https://example.com/users/', id)"
+    format: link
+
+  - name: price
+    type: number
+    sql: unit_price
+    format: currency
+
+  - name: external_id
+    type: number
+    sql: external_system_id
+    format: id
+```
+
+## Supported Formats
+
+### imageUrl
+
+Displays the value as an image in table views:
+
+```yaml
+- name: product_image
+  type: string
+  sql: image_url
+  format: imageUrl
+
+- name: avatar
+  type: string
+  sql: profile_picture_url
+  format: imageUrl
+```
+
+### link
+
+Displays the value as a clickable hyperlink:
+
+```yaml
+- name: website
+  type: string
+  sql: website_url
+  format: link
+
+- name: order_link
+  type: string
+  sql: "CONCAT('https://admin.example.com/orders/', id)"
+  format: link
+```
+
+### id
+
+Prevents number formatting (no commas in large numbers):
+
+```yaml
+- name: external_id
+  type: number
+  sql: external_system_id
+  format: id
+```
+
+Output: `1234567890` instead of `1,234,567,890`
+
+### currency
+
+Displays as monetary value:
+
+```yaml
+- name: unit_price
+  type: number
+  sql: price
+  format: currency
+```
+
+### percent
+
+Displays as percentage:
+
+```yaml
+- name: discount_rate
+  type: number
+  sql: discount
+  format: percent
+```
+
+### Custom Time Format
+
+Use POSIX strftime format strings for time dimensions:
+
+```yaml
+- name: created_at
+  type: time
+  sql: created_at
+  format: "%Y-%m-%d %H:%M:%S"
+
+- name: birth_date
+  type: time
+  sql: birth_date
+  format: "%B %d, %Y"  # "January 15, 2024"
+```
+
+## Time Format Specifiers
+
+| Specifier | Description | Example |
+|-----------|-------------|---------|
+| `%Y` | 4-digit year | 2024 |
+| `%y` | 2-digit year | 24 |
+| `%m` | Month (01-12) | 03 |
+| `%B` | Full month name | March |
+| `%b` | Abbreviated month | Mar |
+| `%d` | Day of month (01-31) | 15 |
+| `%H` | Hour (00-23) | 14 |
+| `%I` | Hour (01-12) | 02 |
+| `%M` | Minute (00-59) | 30 |
+| `%S` | Second (00-59) | 45 |
+| `%p` | AM/PM | PM |
+
+## Common Patterns
+
+### User Profiles
+
+```yaml
+dimensions:
+  - name: avatar
+    type: string
+    sql: avatar_url
+    format: imageUrl
+
+  - name: profile_url
+    type: string
+    sql: "CONCAT('/users/', username)"
+    format: link
+```
+
+### Product Catalog
+
+```yaml
+dimensions:
+  - name: image
+    type: string
+    sql: image_url
+    format: imageUrl
+
+  - name: sku
+    type: string
+    sql: sku
+    format: id
+
+  - name: price
+    type: number
+    sql: price
+    format: currency
+```
+
+### Timestamps
+
+```yaml
+dimensions:
+  - name: created_at
+    type: time
+    sql: created_at
+    format: "%Y-%m-%d"
+
+  - name: last_login
+    type: time
+    sql: last_login_at
+    format: "%b %d, %Y at %I:%M %p"
+```
+
+## BI Tool Support
+
+Format support varies by visualization tool. Most tools recognize common formats, but rendering details may differ.
+
+## See Also
+
+- cubes.dimensions
+- cubes.dimensions.types
+- cubes.measures.format