@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/test/dsl/schema/load.test.ts

@@ -0,0 +1,165 @@
+/**
+ * @module test/schema/load
+ */
+
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DimensionsClient } from "../../../src/dsl/client.js";
+import {
+  DEFAULT_SCHEMA_CACHE_TTL_MS,
+  parseCachePayload,
+  writeSchemaCacheFile,
+} from "../../../src/dsl/schema/cache.js";
+import { clearSchemaCache, loadSchema } from "../../../src/dsl/schema/load.js";
+
+const liveSchema = {
+  sources: { publications: { fields: { year: { type: "int", is_filter: true } } } },
+  entities: { journals: { fields: { title: { type: "string", is_filter: true } } } },
+};
+
+function createMockClient(handlers: {
+  schema?: () => Promise<unknown>;
+  version?: () => Promise<unknown>;
+}): DimensionsClient {
+  return {
+    rawQuery: vi.fn(async (dsl: string) => {
+      if (dsl === "describe schema") {
+        if (!handlers.schema) throw new Error("schema fetch failed");
+        return handlers.schema();
+      }
+      if (dsl === "describe version") {
+        if (!handlers.version) throw new Error("version fetch failed");
+        return handlers.version();
+      }
+      throw new Error(`unexpected query: ${dsl}`);
+    }),
+  } as unknown as DimensionsClient;
+}
+
+describe("loadSchema", () => {
+  let cacheDir: string;
+  let cachePath: string;
+
+  beforeEach(async () => {
+    clearSchemaCache();
+    cacheDir = await mkdtemp(join(tmpdir(), "dsl-schema-cache-"));
+    cachePath = join(cacheDir, "schema.json");
+  });
+
+  afterEach(async () => {
+    clearSchemaCache();
+    await rm(cacheDir, { recursive: true, force: true });
+  });
+
+  it("loads from API and writes cache envelope", async () => {
+    const client = createMockClient({
+      schema: async () => liveSchema,
+      version: async () => ({ version: "2.15.0" }),
+    });
+
+    const store = await loadSchema(client, { cachePath, log: false });
+    expect(store.loadSource).toBe("api");
+    expect(store.stale).toBe(false);
+    expect(store.version).toBe("2.15.0");
+
+    const onDisk = parseCachePayload(JSON.parse(await readFile(cachePath, "utf8")));
+    expect(onDisk?.cachedAt).toBeDefined();
+    expect(onDisk?.version).toBe("2.15.0");
+  });
+
+  it("uses fresh cache without calling the API", async () => {
+    const seedClient = createMockClient({
+      schema: async () => liveSchema,
+      version: async () => ({ version: "2.15.0" }),
+    });
+    await loadSchema(seedClient, { cachePath, log: false });
+
+    clearSchemaCache();
+    const cachedClient = createMockClient({
+      schema: async () => {
+        throw new Error("should not fetch schema");
+      },
+    });
+
+    const store = await loadSchema(cachedClient, {
+      cachePath,
+      cacheTtlMs: DEFAULT_SCHEMA_CACHE_TTL_MS,
+      log: false,
+    });
+
+    expect(store.loadSource).toBe("cache");
+    expect(store.stale).toBe(false);
+    expect(cachedClient.rawQuery).not.toHaveBeenCalled();
+  });
+
+  it("refreshes expired cache from the API", async () => {
+    await writeSchemaCacheFile(cachePath, liveSchema, "2.14.0");
+    const envelope = JSON.parse(await readFile(cachePath, "utf8")) as Record<string, unknown>;
+    envelope.cachedAt = new Date(Date.now() - DEFAULT_SCHEMA_CACHE_TTL_MS - 1000).toISOString();
+    await writeFile(cachePath, JSON.stringify(envelope), "utf8");
+
+    clearSchemaCache();
+    const client = createMockClient({
+      schema: async () => ({
+        ...liveSchema,
+        sources: {
+          ...liveSchema.sources,
+          grants: { fields: { title: { type: "string", is_filter: true } } },
+        },
+      }),
+      version: async () => ({ version: "2.15.0" }),
+    });
+
+    const store = await loadSchema(client, { cachePath, log: false });
+
+    expect(store.loadSource).toBe("api");
+    expect(store.version).toBe("2.15.0");
+    expect(store.sourceNames()).toContain("grants");
+  });
+
+  it("falls back to stale cache when the API is unavailable", async () => {
+    await writeSchemaCacheFile(cachePath, liveSchema, "2.15.0");
+    const envelope = JSON.parse(await readFile(cachePath, "utf8")) as Record<string, unknown>;
+    envelope.cachedAt = new Date(Date.now() - DEFAULT_SCHEMA_CACHE_TTL_MS - 1000).toISOString();
+    await writeFile(cachePath, JSON.stringify(envelope), "utf8");
+
+    clearSchemaCache();
+    const failingClient = createMockClient({
+      schema: async () => {
+        throw new Error("network down");
+      },
+    });
+
+    const store = await loadSchema(failingClient, { cachePath, log: false });
+
+    expect(store.loadSource).toBe("cache");
+    expect(store.stale).toBe(true);
+    expect(store.version).toBe("2.15.0");
+  });
+
+  it("forceRefresh bypasses fresh cache", async () => {
+    const seedClient = createMockClient({
+      schema: async () => liveSchema,
+      version: async () => ({ version: "2.14.0" }),
+    });
+    await loadSchema(seedClient, { cachePath, log: false });
+
+    clearSchemaCache();
+    const refreshClient = createMockClient({
+      schema: async () => liveSchema,
+      version: async () => ({ version: "2.15.0" }),
+    });
+
+    const store = await loadSchema(refreshClient, {
+      cachePath,
+      forceRefresh: true,
+      log: false,
+    });
+
+    expect(store.loadSource).toBe("api");
+    expect(store.version).toBe("2.15.0");
+    expect(refreshClient.rawQuery).toHaveBeenCalled();
+  });
+});

package/test/dsl/schema/summary.test.ts

@@ -0,0 +1,61 @@
+/**
+ * @module test/schema/summary
+ */
+
+import { describe, expect, it } from "vitest";
+import { createSchemaStoreFromResponse } from "../../../src/dsl/schema/store.js";
+import { buildSchemaSummary, SCHEMA_RESOURCE_URIS } from "../../../src/dsl/schema/summary.js";
+
+const sample = {
+  sources: {
+    publications: {
+      fields: {
+        year: { type: "int", is_filter: true, is_facet: true },
+        title: { type: "string", is_filter: true },
+      },
+      search_fields: ["full_data", "title"],
+      metrics: ["times_cited"],
+      fieldsets: { basic: ["id", "title"] },
+    },
+  },
+  entities: { journals: { fields: { title: { type: "string", is_filter: true } } } },
+};
+
+describe("buildSchemaSummary", () => {
+  it("returns compact counts and resource URIs", () => {
+    const store = createSchemaStoreFromResponse(
+      sample,
+      "2.15.0",
+      new Date("2026-01-01T00:00:00Z"),
+      {
+        loadSource: "api",
+        stale: false,
+      },
+    );
+    const summary = buildSchemaSummary(store);
+
+    expect(summary.version).toBe("2.15.0");
+    expect(summary.stats.sourceCount).toBe(1);
+    expect(summary.stats.entityCount).toBe(1);
+    expect(summary.sources.publications.filterableFieldCount).toBe(2);
+    expect(summary.sources.publications.facetFieldCount).toBe(1);
+    expect(summary.sources.publications.searchIndexCount).toBe(2);
+    expect(summary.sources.publications.metricCount).toBe(1);
+    expect(summary.resources).toEqual(SCHEMA_RESOURCE_URIS);
+    expect(summary.hint).toContain("dimensions://fields");
+  });
+
+  it("marks stale cache in the hint", () => {
+    const store = createSchemaStoreFromResponse(sample, "2.15.0", new Date(), {
+      loadSource: "cache",
+      stale: true,
+      cachedAt: new Date("2026-01-01T00:00:00Z"),
+    });
+    const summary = buildSchemaSummary(store);
+
+    expect(summary.stale).toBe(true);
+    expect(summary.loadSource).toBe("cache");
+    expect(summary.cachedAt).toBe("2026-01-01T00:00:00.000Z");
+    expect(summary.hint).toContain("refresh_schema");
+  });
+});

package/test/dsl/schema/validation.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Tests for describe-backed validation helpers.
+ * @module test/schema/validation
+ */
+
+import { describe, expect, it } from "vitest";
+import { ValidationError } from "../../../src/client/index.js";
+import {
+  assertValidEntity,
+  assertValidSearchIndex,
+  createSchemaStoreFromResponse,
+  type DescribeSchemaResponse,
+  QueryBuilder,
+} from "../../../src/dsl/index.js";
+import fixture from "../../fixtures/describe-schema.json";
+
+describe("schema validation", () => {
+  const store = createSchemaStoreFromResponse(fixture as DescribeSchemaResponse);
+
+  it("assertValidEntity accepts sources from describe", () => {
+    expect(() => assertValidEntity(store, "publications")).not.toThrow();
+  });
+
+  it("assertValidEntity rejects unknown sources when store is set", () => {
+    expect(() => assertValidEntity(store, "not_a_source")).toThrow(ValidationError);
+  });
+
+  it("assertValidSearchIndex accepts indexes from describe", () => {
+    expect(() => assertValidSearchIndex(store, "publications", "full_data")).not.toThrow();
+  });
+
+  it("assertValidSearchIndex rejects unknown indexes when store is set", () => {
+    expect(() => assertValidSearchIndex(store, "publications", "not_an_index")).toThrow(
+      ValidationError,
+    );
+  });
+
+  it("QueryBuilder uses schema store when provided", () => {
+    expect(() => new QueryBuilder(store).search("not_a_source")).toThrow(ValidationError);
+    expect(() =>
+      new QueryBuilder(store).search("publications").in("not_an_index").for("test"),
+    ).toThrow(ValidationError);
+    const dsl = new QueryBuilder(store).search("publications").for("test").limit(1).build();
+    expect(dsl).toContain('search publications for "test"');
+  });
+});

package/test/dsl/time-series.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for time-series return functions (citations_per_year, funding_per_year).
+ * @module test/core/time-series
+ */
+
+import { describe, expect, it } from "vitest";
+import { QueryBuilder } from "../../src/dsl/query-builder.js";
+
+describe("QueryBuilder time-series functions", () => {
+  describe("returnCitationsPerYear", () => {
+    it("should generate correct DSL for citations_per_year", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("machine learning")
+        .returnCitationsPerYear(2010, 2023)
+        .build();
+
+      expect(query).toContain("return citations_per_year(2010, 2023)");
+    });
+
+    it("should work with where clauses", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .where("year", ">=", 2020)
+        .returnCitationsPerYear(2020, 2024)
+        .build();
+
+      expect(query).toContain("where year >= 2020");
+      expect(query).toContain("return citations_per_year(2020, 2024)");
+    });
+
+    it("should reject endYear before startYear", () => {
+      expect(() => {
+        new QueryBuilder()
+          .search("publications")
+          .for("test")
+          .returnCitationsPerYear(2024, 2020)
+          .build();
+      }).toThrow(/startYear must not be greater than endYear/);
+    });
+
+    it("should allow same start and end year", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .returnCitationsPerYear(2023, 2023)
+        .build();
+
+      expect(query).toContain("return citations_per_year(2023, 2023)");
+    });
+  });
+
+  describe("returnFundingPerYear", () => {
+    it("should generate correct DSL for funding_per_year with default USD", () => {
+      const query = new QueryBuilder()
+        .search("grants")
+        .for("cancer research")
+        .returnFundingPerYear(2015, 2023)
+        .build();
+
+      expect(query).toContain('return funding_per_year(2015, 2023, "USD")');
+    });
+
+    it("should generate correct DSL with specified currency", () => {
+      const query = new QueryBuilder()
+        .search("grants")
+        .for("test")
+        .returnFundingPerYear(2015, 2023, "EUR")
+        .build();
+
+      expect(query).toContain('return funding_per_year(2015, 2023, "EUR")');
+    });
+
+    it("should support all valid currencies", () => {
+      const currencies = ["AUD", "CAD", "CHF", "CNY", "EUR", "GBP", "JPY", "NZD", "USD"] as const;
+
+      for (const currency of currencies) {
+        const query = new QueryBuilder()
+          .search("grants")
+          .for("test")
+          .returnFundingPerYear(2020, 2024, currency)
+          .build();
+
+        expect(query).toContain(`"${currency}"`);
+      }
+    });
+
+    it("should work with where clauses", () => {
+      const query = new QueryBuilder()
+        .search("grants")
+        .for("test")
+        .where("funding_usd", ">", 1000000)
+        .returnFundingPerYear(2020, 2024, "GBP")
+        .build();
+
+      expect(query).toContain("where funding_usd > 1000000");
+      expect(query).toContain('return funding_per_year(2020, 2024, "GBP")');
+    });
+
+    it("should reject endYear before startYear", () => {
+      expect(() => {
+        new QueryBuilder().search("grants").for("test").returnFundingPerYear(2024, 2020).build();
+      }).toThrow(/startYear must not be greater than endYear/);
+    });
+  });
+
+  describe("combining time-series with entity return", () => {
+    it("should allow entity return before time-series", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fields(["id", "title"])
+        .limit(10)
+        .returnCitationsPerYear(2020, 2024)
+        .build();
+
+      expect(query).toContain("return publications[id+title]");
+      expect(query).toContain("limit 10");
+      expect(query).toContain("return citations_per_year(2020, 2024)");
+    });
+
+    it("should allow both citations and funding in same query (grants)", () => {
+      const query = new QueryBuilder()
+        .search("grants")
+        .for("test")
+        .returnCitationsPerYear(2020, 2024)
+        .returnFundingPerYear(2020, 2024, "USD")
+        .build();
+
+      expect(query).toContain("return citations_per_year(2020, 2024)");
+      expect(query).toContain('return funding_per_year(2020, 2024, "USD")');
+    });
+  });
+});

package/test/dsl/unnest.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Tests for unnest functionality in QueryBuilder and FluentQueryBuilder.
+ * @module test/core/unnest
+ */
+
+import { describe, expect, it } from "vitest";
+import { ValidationError } from "../../src/client/index.js";
+import { QueryBuilder } from "../../src/dsl/query-builder.js";
+
+describe("QueryBuilder unnest", () => {
+  describe("fieldsWithUnnest", () => {
+    it("should generate correct DSL for single unnest", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fieldsWithUnnest(["id", "title"], ["researchers"])
+        .build();
+
+      expect(query).toContain("return publications[id+title+unnest(researchers)]");
+    });
+
+    it("should generate correct DSL for multiple unnests", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fieldsWithUnnest(["id", "title"], ["researchers", "category_for"])
+        .build();
+
+      expect(query).toContain(
+        "return publications[id+title+unnest(researchers)+unnest(category_for)]",
+      );
+    });
+
+    it("should work with only unnest fields (no regular fields)", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fieldsWithUnnest([], ["researchers"])
+        .build();
+
+      expect(query).toContain("return publications[unnest(researchers)]");
+    });
+
+    it("should work with only regular fields (no unnest)", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fieldsWithUnnest(["id", "title"], [])
+        .build();
+
+      expect(query).toContain("return publications[id+title]");
+    });
+
+    it("should combine with where clauses", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("machine learning")
+        .where("year", ">=", 2020)
+        .fieldsWithUnnest(["id", "title"], ["researchers"])
+        .build();
+
+      expect(query).toContain("where year >= 2020");
+      expect(query).toContain("unnest(researchers)");
+    });
+
+    it("should combine with limit", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fieldsWithUnnest(["id"], ["researchers"])
+        .limit(100)
+        .build();
+
+      expect(query).toContain("limit 100");
+      expect(query).toContain("unnest(researchers)");
+    });
+
+    it("should throw for empty field name in unnest", () => {
+      expect(() => {
+        new QueryBuilder()
+          .search("publications")
+          .for("test")
+          .fieldsWithUnnest(["id"], [""])
+          .build();
+      }).toThrow(ValidationError);
+    });
+
+    it("should throw for whitespace-only field name in unnest", () => {
+      expect(() => {
+        new QueryBuilder()
+          .search("publications")
+          .for("test")
+          .fieldsWithUnnest(["id"], ["  "])
+          .build();
+      }).toThrow(ValidationError);
+    });
+  });
+
+  describe("addUnnest", () => {
+    it("should add unnest to existing fields", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fields(["id", "title"])
+        .addUnnest("researchers")
+        .build();
+
+      expect(query).toContain("return publications[id+title+unnest(researchers)]");
+    });
+
+    it("should allow chaining multiple addUnnest calls", () => {
+      const query = new QueryBuilder()
+        .search("publications")
+        .for("test")
+        .fields(["id"])
+        .addUnnest("researchers")
+        .addUnnest("category_for")
+        .build();
+
+      expect(query).toContain("unnest(researchers)");
+      expect(query).toContain("unnest(category_for)");
+    });
+
+    it("should throw for empty field name", () => {
+      expect(() => {
+        new QueryBuilder().search("publications").for("test").fields(["id"]).addUnnest("").build();
+      }).toThrow(ValidationError);
+    });
+  });
+});
+
+describe("Unnest response parsing", () => {
+  // Note: Full response parsing tests would require integration tests
+  // or mocking the client execution
+
+  it("should expect flattened row structure in response", () => {
+    // When unnesting, Dimensions API returns flattened rows
+    // For example, unnesting researchers creates one row per researcher
+    const exampleResponse = {
+      publications: [
+        { id: "pub.123", title: "Paper 1", researchers: { id: "r.1", name: "Alice" } },
+        { id: "pub.123", title: "Paper 1", researchers: { id: "r.2", name: "Bob" } },
+        { id: "pub.456", title: "Paper 2", researchers: { id: "r.1", name: "Alice" } },
+      ],
+    };
+
+    // Same publication can appear multiple times (once per researcher)
+    expect(exampleResponse.publications).toHaveLength(3);
+    expect(exampleResponse.publications.filter((p) => p.id === "pub.123")).toHaveLength(2);
+  });
+});

package/test/dsl/usage-policy.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Tests for Dimensions reasonable-use policy guardrails.
+ * @module test/dsl/usage-policy
+ */
+
+import { describe, expect, it } from "vitest";
+import { ValidationError } from "../../src/client/index.js";
+import {
+  buildExecuteDslPolicyHints,
+  buildUsagePolicy,
+  isFacetOnlyQuery,
+  parseDslPagination,
+  validateExecuteDslPolicy,
+  validateSearchPaginationPolicy,
+} from "../../src/dsl/usage-policy.js";
+
+describe("usage policy", () => {
+  describe("buildUsagePolicy", () => {
+    it("includes limits and guardrail thresholds", () => {
+      const policy = buildUsagePolicy();
+      expect(policy.limits.maxPages).toBe(50);
+      expect(policy.guardrails.largeResultWarningThreshold).toBe(10_000);
+      expect(policy.recommendations.length).toBeGreaterThan(2);
+    });
+  });
+
+  describe("parseDslPagination", () => {
+    it("extracts limit and skip from DSL", () => {
+      expect(
+        parseDslPagination(
+          'search publications for "x" return publications sort by year desc limit 100 skip 5000',
+        ),
+      ).toEqual({ limit: 100, skip: 5000 });
+    });
+  });
+
+  describe("validateSearchPaginationPolicy", () => {
+    it("allows shallow pagination without confirmation", () => {
+      expect(() => validateSearchPaginationPolicy({ skip: 0, limit: 100 })).not.toThrow();
+    });
+
+    it("requires confirmLargeFetch for deep skip", () => {
+      expect(() => validateSearchPaginationPolicy({ skip: 5000, limit: 100 })).toThrow(
+        ValidationError,
+      );
+    });
+
+    it("allows deep skip with confirmation", () => {
+      expect(() =>
+        validateSearchPaginationPolicy({
+          skip: 5000,
+          limit: 100,
+          confirmLargeFetch: true,
+        }),
+      ).not.toThrow();
+    });
+  });
+
+  describe("validateExecuteDslPolicy", () => {
+    it("rejects skip on facet-only queries", () => {
+      expect(() =>
+        validateExecuteDslPolicy({
+          dsl: 'search publications for "ml" return year limit 20 skip 100',
+        }),
+      ).toThrow(/Facet queries cannot be paginated/);
+    });
+
+    it("requires confirmLargeFetch for deep DSL pagination", () => {
+      expect(() =>
+        validateExecuteDslPolicy({
+          dsl: 'search publications for "ml" return publications limit 100 skip 5000',
+        }),
+      ).toThrow(/confirmLargeFetch/);
+    });
+  });
+
+  describe("isFacetOnlyQuery", () => {
+    it("detects facet year returns", () => {
+      expect(isFacetOnlyQuery("search publications return year limit 20")).toBe(true);
+    });
+
+    it("detects entity row returns", () => {
+      expect(isFacetOnlyQuery('search publications for "x" return publications limit 20')).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("buildExecuteDslPolicyHints", () => {
+    it("adds largeResultWarning and paginationHint for big totals", () => {
+      const hints = buildExecuteDslPolicyHints(
+        'search publications for "ml" return publications limit 10',
+        { publications: [], _stats: { total_count: 25_000 } },
+      );
+      expect(hints.largeResultWarning).toContain("25,000");
+      expect(hints.paginationHint).toContain("25");
+      expect(hints.policyNotice).toBeDefined();
+    });
+  });
+});