@malloydata/malloyyo 0.2.12 → 0.2.14

package/dist/index.js

@@ -945,7 +945,9 @@ async function run(runtime, entry, opts = {}) {
     return { ok: false, problems: [errorProblem(e, entry.href)] };
   }
   let query;
-  if (opts.name !== void 0) {
+  if (opts.runExpr !== void 0) {
+    query = materializer.loadQuery(`run: ${opts.runExpr}`);
+  } else if (opts.name !== void 0) {
     if (!modelQueries.named.includes(opts.name)) {
       return {
         ok: false,
@@ -1129,18 +1131,10 @@ function describeGivenSpec(name, g) {
   }
   return spec;
 }
-async function dashboardGivenSpecs(runtime, entry, queryName) {
+async function dashboardGivenSpecs(runtime, entry, runExpr) {
   try {
     const mm = runtime.loadModel(entry);
-    const model = await mm.getModel();
-    const named = [...model.queries().named];
-    if (!named.includes(queryName)) {
-      return {
-        ok: false,
-        error: `no query named '${queryName}' (model has: ${named.join(", ") || "none"})`
-      };
-    }
-    const pq = await mm.loadQueryByName(queryName).getPreparedQuery();
+    const pq = await mm.loadQuery(`run: ${runExpr}`).getPreparedQuery();
     const specs = [];
     for (const [name, g] of pq.givens) {
       specs.push(describeGivenSpec(name, g));
@@ -1158,7 +1152,7 @@ function docText(t) {
     return void 0;
   }
 }
-function readArtifactTag(queryName, q) {
+function readArtifactTag(ident, q) {
   let tag;
   try {
     tag = q.annotations.parseAsTag().tag;
@@ -1168,9 +1162,11 @@ function readArtifactTag(queryName, q) {
   if (!tag.has("artifact")) return void 0;
   const nested = tag.tag("artifact");
   const description = docText(q);
-  const name = nested?.text("name") ?? tag.text("name") ?? queryName;
-  const title = nested?.text("title") ?? tag.text("title") ?? description?.split("\n")[0] ?? queryName;
-  const info = { name, query: queryName, title };
+  const name = nested?.text("name") ?? tag.text("name") ?? ident.defaultName;
+  const title = nested?.text("title") ?? tag.text("title") ?? description?.split("\n")[0] ?? ident.defaultName;
+  const info = { name, query: ident.runExpr, title };
+  if (ident.source) info.source = ident.source;
+  if (ident.view) info.view = ident.view;
   if (description) info.description = description;
   const givensTag = tag.tag("artifact", "givens");
   if (givensTag) {
@@ -1191,9 +1187,25 @@ async function artifactQueries(runtime, entry) {
     const artifacts = [];
     for (const queryName of model.queries().named) {
       const pq = model.getPreparedQueryByName(queryName);
-      const info = readArtifactTag(queryName, pq);
+      const info = readArtifactTag({ runExpr: queryName, defaultName: queryName }, pq);
       if (info) artifacts.push(info);
     }
+    for (const src of model.explores) {
+      for (const field of src.allFields) {
+        if (!field.isQueryField()) continue;
+        const view = field;
+        const info = readArtifactTag(
+          {
+            runExpr: `${src.name} -> ${view.name}`,
+            defaultName: view.name,
+            source: src.name,
+            view: view.name
+          },
+          view
+        );
+        if (info) artifacts.push(info);
+      }
+    }
     return { ok: true, artifacts };
   } catch (e) {
     return { ok: false, error: e instanceof Error ? e.message : String(e) };
@@ -1680,9 +1692,9 @@ async function makeRunner(root) {
   return {
     root: abs,
     entryExists: () => fs.existsSync(path2.join(abs, ENTRY)),
-    run(queryName, givens) {
+    run(runExpr, givens) {
       return lease(
-        (runtime, entry) => run(runtime, entry, { name: queryName, givens, stableResult: true, rowLimit: 5e3 })
+        (runtime, entry) => run(runtime, entry, { runExpr, givens, stableResult: true, rowLimit: 5e3 })
       );
     },
     runText(malloy, givens) {
@@ -1698,22 +1710,16 @@ async function makeRunner(root) {
         return { ok: false, error: msg || "restricted query failed to compile" };
       });
     },
-    givensForQuery(queryName) {
-      return lease((runtime, entry) => dashboardGivenSpecs(runtime, entry, queryName));
+    givensForQuery(runExpr) {
+      return lease((runtime, entry) => dashboardGivenSpecs(runtime, entry, runExpr));
     },
     artifacts() {
       return lease((runtime, entry) => artifactQueries(runtime, entry));
     },
-    validate(queryName, givens) {
+    validate(runExpr, givens) {
       return lease(async (runtime, entry) => {
         try {
-          const mm = runtime.loadModel(entry);
-          const model = await mm.getModel();
-          const named = [...model.queries().named];
-          if (!named.includes(queryName)) {
-            return { ok: false, error: `no query named '${queryName}' (model has: ${named.join(", ") || "none"})` };
-          }
-          const q = mm.loadQueryByName(queryName);
+          const q = runtime.loadModel(entry).loadQuery(`run: ${runExpr}`);
           const has = givens && Object.keys(givens).length > 0;
           await q.getSQL(has ? { givens } : void 0);
           return { ok: true };
@@ -1760,6 +1766,8 @@ async function gatherDashboards(dir) {
   return res.artifacts.map((a) => {
     const tsxPath = join2(dir, "dashboards", a.name, "Dashboard.tsx");
     const manifest = { title: a.title, query: a.query };
+    if (a.source) manifest.source = a.source;
+    if (a.view) manifest.view = a.view;
     if (a.description) manifest.description = a.description;
     if (a.givens) manifest.givens = a.givens;
     return {
@@ -2174,9 +2182,11 @@ with \`malloyyo lint\`.
 server only see what that file EXPORTS. Three things must all be surfaced
 (imported AND exported) through it, or the feature looks broken:
 
-1. **The \`# artifact\`-tagged queries.** Declared in another file and not
-   exported \u2192 \`dashboard dev\` says "No dashboards declared" and \`lint\` says
-   "no dashboards to lint", even though the model compiles clean.
+1. **Whatever holds each \`# artifact\` tag.** A tag on a \`view:\` rides along
+   with its SOURCE (export the source \u2014 you can't export a view on its own); a
+   tag on a top-level \`query:\` needs that query exported. Not surfaced \u2192
+   \`dashboard dev\` says "No dashboards declared" and \`lint\` says "no dashboards
+   to lint", even though the model compiles clean.
 2. **Every filter given the dashboards reference.** An unexported given
    silently resolves to its declaration default \u2014 the control still renders
    but CAN'T CHANGE THE QUERY (the filter looks inert).
@@ -2187,49 +2197,61 @@ server only see what that file EXPORTS. Three things must all be surfaced
 \`\`\`malloy
 ##! experimental.givens
 import {
-  order_items,
+  order_items,                      // the source \u2014 carries its # artifact views
   BRAND, CATEGORY, PERIOD,          // the filter givens
-  brand_suggest,                    // backs a suggest {query=\u2026}
-  overview_dashboard                // the # artifact query
+  brand_suggest                     // backs a suggest {query=\u2026}
 } from 'ecommerce.malloy'
-export { order_items, BRAND, CATEGORY, PERIOD, brand_suggest, overview_dashboard }
+export { order_items, BRAND, CATEGORY, PERIOD, brand_suggest }
 \`\`\`
 
+Exporting the source is often the whole job: its \`# artifact\` views, its
+dimensions (for \`suggest {source=\u2026}\`), and its measures all travel with it.
+
 Prefer \`suggest { query=<named-query> \u2026 }\` over \`suggest { source=\u2026 }\` for
 anything beyond a throwaway: you export one small governed query instead of a
 whole base source.
 
 ## The model is the whole contract
 
-**1. Tag a top-level query** with \`# artifact\` to declare a dashboard. For
-the common overview shape (top-level aggregates + nests), ALSO tag it
-\`# dashboard\` so the result renders as KPI tiles + a card grid instead of one
-flat table \u2014 they're partners: \`# artifact\` declares the dashboard,
-\`# dashboard\` is the renderer tag that draws it like one:
+**1. Tag a \`view:\` inside a source** with \`# artifact\` to declare a dashboard
+(the idiomatic form \u2014 a view is reusable, nestable, and explorable through the
+normal \`query\`/\`describe_source\` surface). For the common overview shape
+(top-level aggregates + nests), ALSO tag it \`# dashboard\` so the result
+renders as KPI tiles + a card grid instead of one flat table \u2014 they're
+partners: \`# artifact\` declares the dashboard, \`# dashboard\` is the renderer
+tag that draws it like one:
 
 \`\`\`malloy
-#" Business health at a glance \u2014 sales, margin, orders.
-# artifact { title="Business Overview" } dashboard
-query: overview_dashboard is order_items -> {
-  where:
-    inventory_items.product_brand ~ $BRAND,     // multi-filter where: is
-    inventory_items.product_category ~ $CATEGORY,  // COMMA separated
-    created_at ~ $PERIOD
-  aggregate: total_sales, total_gross_margin, order_count
-  nest:
-    # line_chart
-    sales_trend is by_month
-    top_brands
-    # shape_map
-    sales_by_state
+source: order_items is \u2026 extend {
+  #" Business health at a glance \u2014 sales, margin, orders.
+  # artifact { title="Business Overview" } dashboard
+  view: overview_dashboard is {
+    where:
+      inventory_items.product_brand ~ $BRAND,     // multi-filter where: is
+      inventory_items.product_category ~ $CATEGORY,  // COMMA separated
+      created_at ~ $PERIOD
+    aggregate: total_sales, total_gross_margin, order_count
+    nest:
+      # line_chart
+      sales_trend is by_month
+      top_brands
+      # shape_map
+      sales_by_state
+  }
 }
 \`\`\`
 
 That's a complete dashboard: the runtime auto-renders a title (the tag's
-\`title\`, else the \`#"\` doc comment), a control for every given the query
-references, and the result panel. \`name="slug"\` overrides the URL/directory
-slug (default: the query name). Note the \`where:\` clauses applying givens are
-COMMA-separated \u2014 newline-separated conditions do not parse.
+\`title\`, else the \`#"\` doc comment), a control for every given the view
+references, and the result panel. It runs as \`run: <source> -> <view>\` (here
+\`order_items -> overview_dashboard\`). \`name="slug"\` overrides the
+URL/directory slug (default: the view name). Note the \`where:\` clauses
+applying givens are COMMA-separated \u2014 newline-separated conditions do not
+parse.
+
+Tagging a **top-level \`query:\`** still works and behaves identically (it runs
+as \`run: <name>\`) \u2014 reach for it only when the dashboard query doesn't belong
+to any one source.
 
 Two dashboards can share a given but start on different values \u2014 a \`givens\`
 block in the tag sets PER-DASHBOARD defaults (given values, i.e. filter
@@ -2282,6 +2304,25 @@ equals, not colon):
   (\`\u2026 + { where: lower(field) ~ f'll%'; limit: 50 }\`, case-insensitive,
   escaped). Without a dimension the fetched list is filtered client-side.
   Runs as a restricted query; lint checks the declaration compiles.
+
+  **RELATED (faceted) filters** \u2014 query-form only: a suggest query may
+  reference the OTHER givens, and the runtime runs it with the dashboard's
+  current values (the suggested given itself is excluded, so the list never
+  collapses to the current pick). Brand suggestions narrow when Category is
+  set:
+
+  \`\`\`malloy
+  query: brand_suggest is inventory_items -> product_brand + {
+    where:
+      product_category ~ $CATEGORY,      // NOT product_brand ~ $BRAND
+      product_department ~ $DEPARTMENT
+    limit: 500
+  }
+  \`\`\`
+
+  Declare one \`*_suggest\` per filter, each referencing the others; \`f''\`
+  defaults mean unset filters don't constrain. \`source=\` suggests can't do
+  this (no place for a \`where:\`) \u2014 another reason to prefer \`query=\`.
 - \`control=select\` \u2014 a fixed dropdown instead of a typeahead search box
 - \`range_min\` / \`range_max\` \u2014 bounds; makes a filter<number> given a
   dual-thumb range slider
@@ -2381,11 +2422,12 @@ usually means the \`# artifact\` queries aren't exported through
 
 Validation loop that works well: the local \`malloyyo mcp\` server hot-reloads
 working-directory edits \u2014 \`query(execute:false)\` to compile-check,
-\`execute:true\` to run. A top-level \`# artifact\` query runs as
-\`run: <name>\` (not \`source -> <name>\`), and is only visible once exported
-through the entry. Don't validate local edits against a hosted/claude.ai
-connector \u2014 that serves the PUBLISHED model, which is stale until
-\`malloyyo publish\`.
+\`execute:true\` to run. A \`# artifact\` view runs as
+\`run: <source> -> <view>\`; a top-level \`# artifact\` query runs as
+\`run: <name>\`. Either is only visible once surfaced through the entry (export
+the source for a view, the query for a top-level query). Don't validate local
+edits against a hosted/claude.ai connector \u2014 that serves the PUBLISHED model,
+which is stale until \`malloyyo publish\`.
 `;
 
 // src/mcp.ts
@@ -2771,7 +2813,7 @@ async function serveDashboard(opts) {
 }
 
 // package.json
-var version = "0.2.12";
+var version = "0.2.14";
 
 // src/index.ts
 function shortSha(sha) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloyyo",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Publish Malloy models to a Malloyyo instance",
   "license": "MIT",
   "repository": {