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

package/test/dsl/integration/special-functions.integration.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Integration tests for DSL Special Functions.
+ * Tests similar_documents, classify, and extract_concepts against the real Dimensions API.
+ * @module test/integration/special-functions.integration
+ */
+
+import { beforeAll, describe, expect, it } from "vitest";
+import { DimensionsClient } from "../../../../src/dsl/index.js";
+
+import { loadTestConfig } from "./test-config.js";
+
+const config = loadTestConfig(); // was: process.env.DIMENSIONS_API_KEY
+const TIMEOUT = 30_000;
+
+describe.skipIf(!config)("Special Functions Integration", () => {
+  let client: DimensionsClient;
+
+  beforeAll(() => {
+    client = new DimensionsClient({
+      apiKey: config!.apiKey,
+      ...(config!.baseUrl && { baseUrl: config!.baseUrl }),
+      rateLimitPerMinute: 30,
+    });
+  });
+
+  describe("similar_documents()", () => {
+    it(
+      "finds similar publications based on abstract text",
+      async () => {
+        // Sample abstract text for semantic matching
+        const abstractText = `After spinal cord injury, macrophages infiltrate the lesion site
+        and contribute to both tissue damage and repair processes. Understanding the
+        mechanisms of macrophage polarization could lead to novel therapeutic strategies.`;
+
+        const dsl = `search publications for similar_documents("${abstractText.replace(/"/g, '\\"').replace(/\n/g, " ")}")
+        where year > 2015
+        return publications[id+title+year] limit 5`;
+
+        const response = await client.rawQuery(dsl);
+
+        console.log("similar_documents response:", JSON.stringify(response, null, 2));
+
+        expect(response).toBeDefined();
+        // Check if publications array exists
+        if ("publications" in response) {
+          expect(Array.isArray(response.publications)).toBe(true);
+          const pubs = response.publications as Array<{ id: string; title: string; year: number }>;
+          expect(pubs.length).toBeGreaterThan(0);
+          expect(pubs.length).toBeLessThanOrEqual(5);
+
+          // Verify structure
+          for (const pub of pubs) {
+            expect(pub.id).toBeDefined();
+            expect(pub.title).toBeDefined();
+          }
+        }
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "finds similar grants based on description text",
+      async () => {
+        const descriptionText = `Development of novel cancer immunotherapy approaches using
+        checkpoint inhibitors and CAR-T cell engineering for solid tumors.`;
+
+        const dsl = `search grants for similar_documents("${descriptionText.replace(/"/g, '\\"')}")
+        where start_year >= 2020
+        return grants[id+title+funder_org_name] limit 5`;
+
+        const response = await client.rawQuery(dsl);
+
+        console.log("similar_documents grants response:", JSON.stringify(response, null, 2));
+
+        expect(response).toBeDefined();
+        if ("grants" in response) {
+          expect(Array.isArray(response.grants)).toBe(true);
+        }
+      },
+      TIMEOUT,
+    );
+  });
+
+  describe("complex()", () => {
+    it(
+      "finds publications using proximity search",
+      async () => {
+        const dsl = `search publications for complex("CRISPR gene editing", 5) return publications[id+title] limit 5`;
+
+        const response = await client.rawQuery(dsl);
+
+        expect(response).toBeDefined();
+        if ("publications" in response) {
+          expect(Array.isArray(response.publications)).toBe(true);
+          const pubs = response.publications as Array<{ id: string; title: string }>;
+          expect(pubs.length).toBeGreaterThan(0);
+          expect(pubs.length).toBeLessThanOrEqual(5);
+
+          for (const pub of pubs) {
+            expect(pub.id).toBeDefined();
+            expect(pub.title).toBeDefined();
+          }
+        }
+      },
+      TIMEOUT,
+    );
+  });
+
+  describe("min_should_match()", () => {
+    it(
+      "finds publications matching minimum terms",
+      async () => {
+        const dsl = `search publications for min_should_match("quantum optical networking", 2) return publications[id+title] limit 5`;
+
+        const response = await client.rawQuery(dsl);
+
+        expect(response).toBeDefined();
+        if ("publications" in response) {
+          expect(Array.isArray(response.publications)).toBe(true);
+          const pubs = response.publications as Array<{ id: string; title: string }>;
+          expect(pubs.length).toBeLessThanOrEqual(5);
+        }
+      },
+      TIMEOUT,
+    );
+  });
+
+  describe("classify()", () => {
+    it(
+      "classifies text using FOR (Fields of Research) system",
+      async () => {
+        const dsl = `classify(
+        title="Burnout and intentions to quit the nursing profession",
+        abstract="BACKGROUND: Burnout is an occupational disease that affects healthcare workers. This study examines the relationship between burnout and turnover intentions among nurses.",
+        system="FOR"
+      )`;
+
+        const response = await client.rawQuery(dsl);
+
+        console.log("classify FOR response:", JSON.stringify(response, null, 2));
+
+        expect(response).toBeDefined();
+        // Expected structure: array of classification codes with scores
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "classifies text using SDG (Sustainable Development Goals) system",
+      async () => {
+        const dsl = `classify(
+        title="Climate change impacts on coastal communities",
+        abstract="This study examines the effects of rising sea levels and extreme weather events on vulnerable coastal populations in developing nations.",
+        system="SDG"
+      )`;
+
+        const response = await client.rawQuery(dsl);
+
+        console.log("classify SDG response:", JSON.stringify(response, null, 2));
+
+        expect(response).toBeDefined();
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "classifies text using RCDC system",
+      async () => {
+        const dsl = `classify(
+        title="Novel therapeutic targets for Alzheimer's disease",
+        abstract="This research investigates the role of tau protein aggregation in neurodegeneration and identifies potential drug targets for treating Alzheimer's disease.",
+        system="RCDC"
+      )`;
+
+        const response = await client.rawQuery(dsl);
+
+        console.log("classify RCDC response:", JSON.stringify(response, null, 2));
+
+        expect(response).toBeDefined();
+      },
+      TIMEOUT,
+    );
+  });
+
+  describe("extract_concepts()", () => {
+    it(
+      "extracts concepts from abstract text",
+      async () => {
+        const abstractText = `After spinal cord injury, macrophages infiltrate the lesion site
+        and contribute to both tissue damage and repair. M1 macrophages promote inflammation
+        while M2 macrophages support tissue regeneration and axon regrowth.`;
+
+        const dsl = `extract_concepts("${abstractText.replace(/"/g, '\\"').replace(/\n/g, " ")}")`;
+
+        const response = await client.rawQuery(dsl);
+
+        console.log("extract_concepts response:", JSON.stringify(response, null, 2));
+
+        expect(response).toBeDefined();
+        // Expected: array of concept strings
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "extracts concepts with scores",
+      async () => {
+        const abstractText = `Machine learning algorithms including neural networks and
+        deep learning architectures are revolutionizing drug discovery and precision medicine.`;
+
+        // Try without text= named parameter - just positional
+        const dsl = `extract_concepts("${abstractText.replace(/"/g, '\\"').replace(/\n/g, " ")}", return_scores=true)`;
+
+        const response = await client.rawQuery(dsl);
+
+        console.log("extract_concepts with scores response:", JSON.stringify(response, null, 2));
+
+        expect(response).toBeDefined();
+        // Expected: array of concepts with relevance scores
+      },
+      TIMEOUT,
+    );
+  });
+});

package/test/dsl/integration/test-config.ts

@@ -0,0 +1,52 @@
+/**
+ * Test configuration loader for integration tests.
+ * Loads API credentials from environment or config file.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface TestConfig {
+  apiKey: string;
+  baseUrl?: string;
+}
+
+/**
+ * Loads test configuration from environment variables or config file.
+ */
+export function loadTestConfig(): TestConfig | undefined {
+  // Priority 1: Environment variables
+  if (process.env.DIMENSIONS_API_KEY) {
+    return {
+      apiKey: process.env.DIMENSIONS_API_KEY,
+      baseUrl: process.env.DIMENSIONS_BASE_URL,
+    };
+  }
+
+  // Priority 2: Config file in project root
+  const configPaths = [
+    join(process.cwd(), ".dimensions.config.json"),
+    join(process.cwd(), ".dimensions.config.json"),
+    join(process.cwd(), "apps", "mcp", ".dimensions.config.json"),
+  ];
+
+  for (const configPath of configPaths) {
+    if (existsSync(configPath)) {
+      try {
+        const content = readFileSync(configPath, "utf-8");
+        const config = JSON.parse(content);
+        // Config uses nested structure: { dsl: { apiKey, baseUrl } }
+        if (config.dsl?.apiKey) {
+          return {
+            apiKey: config.dsl.apiKey,
+            baseUrl: config.dsl.baseUrl,
+          };
+        }
+      } catch {
+        // Continue to next path
+      }
+    }
+  }
+
+  return undefined;
+}

package/test/dsl/pagination.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Tests for Dimensions pagination helpers.
+ * @module test/dsl/pagination
+ */
+
+import { describe, expect, it } from "vitest";
+import { ValidationError } from "../../src/client/index.js";
+import {
+  buildPaginationMetadata,
+  CONFIRM_LARGE_FETCH_PAGES,
+  resolveSkipAndLimit,
+  validateBatchPagination,
+  validatePaginationBounds,
+} from "../../src/dsl/pagination.js";
+
+describe("pagination helpers", () => {
+  describe("resolveSkipAndLimit", () => {
+    it("defaults to skip 0 and limit 100", () => {
+      expect(resolveSkipAndLimit({})).toEqual({ skip: 0, limit: 100 });
+    });
+
+    it("computes skip from page", () => {
+      expect(resolveSkipAndLimit({ page: 2, limit: 500 })).toEqual({ skip: 1000, limit: 500 });
+    });
+
+    it("prefers skip when skip and page are both set", () => {
+      expect(resolveSkipAndLimit({ skip: 100, page: 1, limit: 100 })).toEqual({
+        skip: 100,
+        limit: 100,
+      });
+    });
+
+    it("rejects skip + limit beyond max offset", () => {
+      expect(() => resolveSkipAndLimit({ skip: 49500, limit: 1000 })).toThrow(ValidationError);
+    });
+  });
+
+  describe("buildPaginationMetadata", () => {
+    it("includes nextSkip when more results exist", () => {
+      const meta = buildPaginationMetadata(0, 100, 5000);
+      expect(meta.nextSkip).toBe(100);
+      expect(meta.estimatedRequestsToFetchAll).toBe(50);
+      expect(meta.maxPagesRemaining).toBeGreaterThan(0);
+    });
+
+    it("sets nextSkip null on last page", () => {
+      const meta = buildPaginationMetadata(4900, 100, 5000);
+      expect(meta.nextSkip).toBeNull();
+    });
+  });
+
+  describe("validateBatchPagination", () => {
+    it("allows small batch without confirmation", () => {
+      expect(() =>
+        validateBatchPagination({ startPage: 0, maxPages: 3, pageSize: 1000 }),
+      ).not.toThrow();
+    });
+
+    it("requires confirmLargeFetch for many pages", () => {
+      expect(() =>
+        validateBatchPagination({
+          startPage: 0,
+          maxPages: CONFIRM_LARGE_FETCH_PAGES + 1,
+          pageSize: 1000,
+        }),
+      ).toThrow(ValidationError);
+    });
+
+    it("allows large batch with confirmation", () => {
+      expect(() =>
+        validateBatchPagination({
+          startPage: 0,
+          maxPages: 10,
+          pageSize: 1000,
+          confirmLargeFetch: true,
+        }),
+      ).not.toThrow();
+    });
+  });
+
+  describe("validatePaginationBounds", () => {
+    it("accepts boundary skip", () => {
+      expect(() => validatePaginationBounds(49000, 1000)).not.toThrow();
+    });
+  });
+});