@malloy-publisher/server 0.0.198 → 0.0.199

package/src/service/given.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared utilities for surfacing Malloy `Given` declarations on
+ * compiled models.
+ *
+ * The Malloy SDK's `Given` class is declared in
+ * `@malloydata/malloy/dist/api/foundation/core.d.ts` but is not
+ * re-exported from the package root, so we duck-type against the
+ * surface we actually use and don't pull in the private type.
+ *
+ * Lives here so both the main-thread `Model` constructor and the
+ * package-load worker can use the same conversion. The worker
+ * imports this file directly (it's pure TypeScript with no native
+ * deps, so it's safe to bundle into the worker entry).
+ */
+
+/**
+ * Duck-typed shape of a Malloy SDK `Given` instance (the value type
+ * of `Model.givens`).
+ */
+export interface MalloyGiven {
+   readonly name: string;
+   readonly type: { type: string; filterType?: string };
+   getTaglines(prefix?: RegExp): string[];
+}
+
+/**
+ * Wire/API shape of a given. Structurally identical to the
+ * `components["schemas"]["Given"]` shape from the OpenAPI spec —
+ * callers can cast freely.
+ */
+export interface MalloyGivenApi {
+   name: string;
+   type: string;
+   annotations?: string[];
+}
+
+/**
+ * Convert a Malloy SDK `Given` to the wire/API shape.
+ *
+ * Two fields are deliberately not surfaced:
+ *
+ * - `location` — Malloy's `DocumentLocation.url` is an absolute
+ *   `file://` path on the publisher's filesystem. Surfacing it
+ *   would leak the OS user, install directory, and internal
+ *   layout. Existing `Filter` introspection does not expose
+ *   location either; matching that floor. A future PR can add a
+ *   sanitised package-relative path if a client needs it.
+ *
+ * - `default` / `defaultText` — Malloy's API only exposes the
+ *   parsed `ConstantExpr` AST, not a rendered source string.
+ *   Rendering it here would duplicate the Malloy printer. Add
+ *   when Malloy surfaces a stringified accessor.
+ *
+ * `annotations` is restricted to `#(...)` declaration annotations
+ * (the caller-facing kind, e.g. `#(doc)`). `getTaglines()` with no
+ * prefix would also return `##` doc-comment lines and the
+ * model-level `##!` pragma, which aren't part of the given's
+ * surface contract.
+ *
+ * Type rendering: `GivenTypeDef` is typed as `AtomicTypeDef |
+ * FilterExpressionParamTypeDef`, but Malloy's grammar only emits
+ * the scalar parameter types (`string` | `number` | `boolean` |
+ * `date` | `timestamp` | `timestamptz` | `filter expression` |
+ * `error`) for given declarations today. If the grammar expands
+ * to allow array or record givens, the bare `type.type`
+ * discriminator (`'array'`, `'record'`) will land in the wire
+ * response with no element info — revisit when that happens.
+ */
+export function malloyGivenToApi(given: MalloyGiven): MalloyGivenApi {
+   const type = given.type;
+   const renderedType =
+      type.type === "filter expression"
+         ? `filter<${type.filterType}>`
+         : type.type;
+   return {
+      name: given.name,
+      type: renderedType,
+      annotations: given.getTaglines(/^#\(/),
+   };
+}

package/src/service/givens_integration.spec.ts

@@ -0,0 +1,192 @@
+import { DuckDBConnection } from "@malloydata/db-duckdb";
+import { Connection } from "@malloydata/malloy";
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { Model } from "./model";
+
+const TEST_DIR = path.join(os.tmpdir(), "givens-integration-tests");
+const TEST_DB_DIR = path.join(TEST_DIR, "db");
+const TEST_DB_PATH = path.join(TEST_DB_DIR, "test.duckdb");
+const TEST_PKG_DIR = path.join(TEST_DIR, "pkg");
+
+let duckdbConnection: DuckDBConnection;
+
+const SEED_SQL = `
+CREATE TABLE IF NOT EXISTS orders (
+   order_id INTEGER,
+   region VARCHAR,
+   order_date DATE
+);
+INSERT INTO orders VALUES
+   (1, 'US', '2024-01-15'),
+   (2, 'EU', '2024-02-10'),
+   (3, 'APAC', '2024-03-05');
+`;
+
+const MODEL_WITH_GIVENS = `
+##! experimental.givens
+
+given: region_filter :: string is 'US'
+given: cutoff_date :: date is @2024-02-01
+
+source: orders is duckdb.table('orders') extend {
+   primary_key: order_id
+
+   measure: order_count is count()
+}
+`;
+
+const MODEL_WITHOUT_GIVENS = `
+source: orders is duckdb.table('orders') extend {
+   primary_key: order_id
+
+   measure: order_count is count()
+}
+`;
+
+const MODEL_WITH_ANNOTATED_GIVEN = `
+##! experimental.givens
+
+#(doc) Region code, e.g. US, EU
+#(label) Region
+given: region_filter :: string is 'US'
+
+source: orders is duckdb.table('orders') extend {
+   primary_key: order_id
+}
+`;
+
+beforeAll(async () => {
+   await fs.mkdir(TEST_DB_DIR, { recursive: true });
+   await fs.mkdir(TEST_PKG_DIR, { recursive: true });
+   duckdbConnection = new DuckDBConnection("duckdb", TEST_DB_PATH, TEST_DB_DIR);
+   for (const stmt of SEED_SQL.trim().split(";").filter(Boolean)) {
+      await duckdbConnection.runSQL(stmt.trim() + ";");
+   }
+   // Each fixture lives in its own file. Tests share `beforeAll` for harness
+   // setup but never edit these files at runtime, so no `beforeEach` /
+   // `afterEach` cleanup is needed.
+   await fs.writeFile(
+      path.join(TEST_PKG_DIR, "orders.malloy"),
+      MODEL_WITH_GIVENS,
+      "utf-8",
+   );
+   await fs.writeFile(
+      path.join(TEST_PKG_DIR, "orders_no_givens.malloy"),
+      MODEL_WITHOUT_GIVENS,
+      "utf-8",
+   );
+   await fs.writeFile(
+      path.join(TEST_PKG_DIR, "orders_annotated.malloy"),
+      MODEL_WITH_ANNOTATED_GIVEN,
+      "utf-8",
+   );
+});
+
+afterAll(async () => {
+   try {
+      await duckdbConnection.close();
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      await fs.rm(TEST_DIR, { recursive: true, force: true });
+   } catch {
+      // Ignore cleanup errors
+   }
+});
+
+function getConnections(): Map<string, Connection> {
+   const map = new Map<string, Connection>();
+   map.set("duckdb", duckdbConnection);
+   return map;
+}
+
+describe("givens introspection", () => {
+   it("surfaces declared givens on the compiled-model response", async () => {
+      const model = await Model.create(
+         "test-pkg",
+         TEST_PKG_DIR,
+         "orders.malloy",
+         getConnections(),
+      );
+
+      const compiledModel = await model.getModel();
+
+      expect(compiledModel.givens).toBeDefined();
+      expect(compiledModel.givens).toHaveLength(2);
+
+      const byName = new Map(
+         (compiledModel.givens ?? []).map((g) => [g.name, g]),
+      );
+      const region = byName.get("region_filter");
+      const cutoff = byName.get("cutoff_date");
+
+      expect(region).toBeDefined();
+      expect(region?.type).toBe("string");
+      expect(cutoff).toBeDefined();
+      expect(cutoff?.type).toBe("date");
+   });
+
+   it("attaches the model-level givens list to every source", async () => {
+      const model = await Model.create(
+         "test-pkg",
+         TEST_PKG_DIR,
+         "orders.malloy",
+         getConnections(),
+      );
+
+      const sources = model.getSources();
+      expect(sources).toBeDefined();
+      expect(sources).toHaveLength(1);
+
+      const ordersSource = sources?.[0];
+      expect(ordersSource?.name).toBe("orders");
+      expect(ordersSource?.givens).toBeDefined();
+      expect(ordersSource?.givens).toHaveLength(2);
+
+      const names = (ordersSource?.givens ?? []).map((g) => g.name).sort();
+      expect(names).toEqual(["cutoff_date", "region_filter"]);
+   });
+
+   it("returns undefined for givens when the model declares none", async () => {
+      const model = await Model.create(
+         "test-pkg",
+         TEST_PKG_DIR,
+         "orders_no_givens.malloy",
+         getConnections(),
+      );
+
+      const compiledModel = await model.getModel();
+
+      // Absent rather than empty: matches how `sources`/`queries` behave when
+      // there are none, and lets OpenAPI clients distinguish "feature
+      // unsupported" from "supported but no declarations."
+      expect(compiledModel.givens).toBeUndefined();
+      expect(model.getSources()?.[0]?.givens).toBeUndefined();
+   });
+
+   it("surfaces only `#(...)` annotations, not pragmas or doc comments", async () => {
+      const model = await Model.create(
+         "test-pkg",
+         TEST_PKG_DIR,
+         "orders_annotated.malloy",
+         getConnections(),
+      );
+
+      const compiledModel = await model.getModel();
+
+      expect(compiledModel.givens).toHaveLength(1);
+      const region = compiledModel.givens?.[0];
+      expect(region?.name).toBe("region_filter");
+
+      // The model declares two `#(...)` annotations plus a `##!` pragma.
+      // Only the `#(...)` lines should land on the wire.
+      const annotations = region?.annotations ?? [];
+      expect(annotations.length).toBeGreaterThanOrEqual(2);
+      for (const line of annotations) {
+         expect(line.startsWith("#(")).toBe(true);
+      }
+      // Negative assertion: no pragma leakage.
+      expect(annotations.some((a) => a.startsWith("##!"))).toBe(false);
+   });
+});

package/src/service/model.spec.ts

@@ -234,6 +234,111 @@ describe("service/model", () => {
 
             sinon.restore();
          });
+
+         it("forwards givens to runnable.getPreparedResult and .run", async () => {
+            const givensArg = { region: "EU" };
+            const preparedResultStub = sinon
+               .stub()
+               .resolves({ resultExplore: { limit: 10 } });
+            const runStub = sinon
+               .stub()
+               .rejects(new MalloyError("stub-stop", []));
+            const modelMaterializer = {
+               loadQuery: sinon.stub().returns({
+                  getPreparedResult: preparedResultStub,
+                  run: runStub,
+               }),
+            };
+
+            const model = new Model(
+               packageName,
+               mockModelPath,
+               {},
+               "model",
+               // eslint-disable-next-line @typescript-eslint/no-explicit-any
+               modelMaterializer as any,
+               // eslint-disable-next-line @typescript-eslint/no-explicit-any
+               { contents: {}, exports: [], queryList: [] } as any,
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+            );
+
+            await expect(
+               model.getQueryResults(
+                  undefined,
+                  undefined,
+                  "run: orders -> summary",
+                  undefined,
+                  undefined,
+                  givensArg,
+               ),
+            ).rejects.toThrow(MalloyError);
+
+            expect(preparedResultStub.calledOnce).toBe(true);
+            expect(preparedResultStub.firstCall.args[0]).toEqual({
+               givens: givensArg,
+            });
+            expect(runStub.firstCall.args[0]).toMatchObject({
+               givens: givensArg,
+            });
+
+            sinon.restore();
+         });
+      });
+
+      describe("executeNotebookCell", () => {
+         it("forwards givens to runnable.getPreparedResult and .run", async () => {
+            const givensArg = { target_code: "AA" };
+            const preparedResultStub = sinon
+               .stub()
+               .resolves({ resultExplore: { limit: 10 } });
+            const runStub = sinon
+               .stub()
+               .rejects(new MalloyError("stub-stop", []));
+            const cellRunnable = {
+               getPreparedResult: preparedResultStub,
+               run: runStub,
+            };
+            const runnableCells = [
+               {
+                  type: "code" as const,
+                  text: "run: orders -> by_code",
+                  runnable: cellRunnable,
+               },
+            ];
+
+            const model = new Model(
+               packageName,
+               "test.malloynb",
+               {},
+               "notebook",
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+               // eslint-disable-next-line @typescript-eslint/no-explicit-any
+               runnableCells as any,
+               undefined,
+            );
+
+            await expect(
+               model.executeNotebookCell(0, undefined, undefined, givensArg),
+            ).rejects.toThrow(MalloyError);
+
+            expect(preparedResultStub.calledOnce).toBe(true);
+            expect(preparedResultStub.firstCall.args[0]).toEqual({
+               givens: givensArg,
+            });
+            expect(runStub.firstCall.args[0]).toMatchObject({
+               givens: givensArg,
+            });
+
+            sinon.restore();
+         });
       });
    });