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

package/test/dsl/utils/escape.property.test.ts

@@ -0,0 +1,109 @@
+import * as fc from "fast-check";
+import { describe, expect, it } from "vitest";
+import { escapeDslString } from "../../../src/dsl/utils/escape.js";
+import { unescapeString } from "../../../src/dsl/utils/string-utils.js";
+
+/**
+ * Checks whether a string contains an unescaped double quote.
+ * Walks character-by-character, tracking backslash escaping.
+ */
+function containsUnescapedQuote(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\") {
+      i++; // skip next char (it's escaped)
+      continue;
+    }
+    if (s[i] === '"') return true;
+  }
+  return false;
+}
+
+/** Arbitrary that generates strings with full Unicode codepoints (including astral plane). */
+const unicodeString = fc
+  .array(
+    fc
+      .integer({ min: 0, max: 0x10ffff })
+      .filter((n) => n < 0xd800 || n > 0xdfff)
+      .map((n) => String.fromCodePoint(n)),
+    { maxLength: 100 },
+  )
+  .map((arr) => arr.join(""));
+
+/** Arbitrary that generates strings dense with characters escapeDslString handles. */
+const adversarial = fc
+  .array(
+    fc.constantFrom('"', "\\", "\n", "\t", "\r", "\b", "\f", "\u201c", "\u201d", "a", " ", "\0"),
+    { maxLength: 200 },
+  )
+  .map((arr) => arr.join(""));
+
+describe("escapeDslString property tests", () => {
+  describe("P1: no unescaped double quote in output", () => {
+    it("holds for arbitrary ASCII strings", () => {
+      fc.assert(
+        fc.property(fc.string(), (s) => {
+          expect(containsUnescapedQuote(escapeDslString(s))).toBe(false);
+        }),
+        { numRuns: 200 },
+      );
+    });
+
+    it("holds for full unicode strings", () => {
+      fc.assert(
+        fc.property(unicodeString, (s) => {
+          expect(containsUnescapedQuote(escapeDslString(s))).toBe(false);
+        }),
+        { numRuns: 200 },
+      );
+    });
+
+    it("holds for adversarial strings", () => {
+      fc.assert(
+        fc.property(adversarial, (s) => {
+          expect(containsUnescapedQuote(escapeDslString(s))).toBe(false);
+        }),
+        { numRuns: 50 },
+      );
+    });
+  });
+
+  describe("P2: roundtrip with unescapeString", () => {
+    it("holds for arbitrary ASCII strings", () => {
+      fc.assert(
+        fc.property(fc.string(), (s) => {
+          expect(unescapeString(escapeDslString(s))).toBe(s);
+        }),
+        { numRuns: 200 },
+      );
+    });
+
+    it("holds for full unicode strings", () => {
+      fc.assert(
+        fc.property(unicodeString, (s) => {
+          expect(unescapeString(escapeDslString(s))).toBe(s);
+        }),
+        { numRuns: 200 },
+      );
+    });
+
+    it("holds for adversarial strings", () => {
+      fc.assert(
+        fc.property(adversarial, (s) => {
+          expect(unescapeString(escapeDslString(s))).toBe(s);
+        }),
+        { numRuns: 50 },
+      );
+    });
+  });
+
+  describe("P3: output length >= input length", () => {
+    it("escaping never shrinks the string", () => {
+      fc.assert(
+        fc.property(fc.string(), (s) => {
+          expect(escapeDslString(s).length).toBeGreaterThanOrEqual(s.length);
+        }),
+        { numRuns: 200 },
+      );
+    });
+  });
+});

package/test/dsl/utils/escape.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import { escapeDslString } from "../../../src/dsl/utils/escape.js";
+
+describe("escapeDslString", () => {
+  it("escapes double quotes", () => {
+    expect(escapeDslString('hello "world"')).toBe('hello \\"world\\"');
+  });
+
+  it("escapes backslashes", () => {
+    expect(escapeDslString("path\\to\\file")).toBe("path\\\\to\\\\file");
+  });
+
+  it("escapes newlines", () => {
+    expect(escapeDslString("line one\nline two")).toBe("line one\\nline two");
+  });
+
+  it("handles combined special characters", () => {
+    expect(escapeDslString('say "hello"\nnew\\line')).toBe('say \\"hello\\"\\nnew\\\\line');
+  });
+
+  it("returns empty string unchanged", () => {
+    expect(escapeDslString("")).toBe("");
+  });
+
+  it("returns string with no special characters unchanged", () => {
+    expect(escapeDslString("plain text")).toBe("plain text");
+  });
+
+  it("escapes injection payload", () => {
+    const payload = 'test" return publications limit 9999 //';
+    expect(escapeDslString(payload)).toBe('test\\" return publications limit 9999 //');
+  });
+
+  it("escapes backslash before quote (double escape)", () => {
+    expect(escapeDslString('a\\"b')).toBe('a\\\\\\"b');
+  });
+
+  it("escapes left smart quote (U+201C)", () => {
+    expect(escapeDslString("say \u201chello\u201d")).toBe("say \\\u201chello\\\u201d");
+  });
+
+  it("escapes right smart quote (U+201D)", () => {
+    expect(escapeDslString("\u201dend")).toBe("\\\u201dend");
+  });
+
+  it("escapes tab character", () => {
+    expect(escapeDslString("col1\tcol2")).toBe("col1\\tcol2");
+  });
+
+  it("escapes carriage return", () => {
+    expect(escapeDslString("line\r\nbreak")).toBe("line\\r\\nbreak");
+  });
+
+  it("escapes backspace and form feed", () => {
+    expect(escapeDslString("a\bb\fc")).toBe("a\\bb\\fc");
+  });
+
+  it("escapes smart quote injection payload", () => {
+    const payload = "test\u201d return publications limit 9999 //";
+    expect(escapeDslString(payload)).toBe(
+      "\\\u201d return publications limit 9999 //".replace(/^/, "test"),
+    );
+  });
+
+  // --- Null byte ---
+  it("escapes embedded null byte", () => {
+    expect(escapeDslString("before\0after")).toBe("before\\u0000after");
+  });
+
+  it("escapes standalone null byte", () => {
+    expect(escapeDslString("\0")).toBe("\\u0000");
+  });
+
+  // --- C0 controls ---
+  it("escapes SOH (U+0001)", () => {
+    expect(escapeDslString("\u0001")).toBe("\\u0001");
+  });
+
+  it("escapes US (U+001F)", () => {
+    expect(escapeDslString("\u001f")).toBe("\\u001f");
+  });
+
+  it("preserves named escapes for C0 characters", () => {
+    expect(escapeDslString("\n")).toBe("\\n");
+    expect(escapeDslString("\t")).toBe("\\t");
+    expect(escapeDslString("\r")).toBe("\\r");
+    expect(escapeDslString("\b")).toBe("\\b");
+    expect(escapeDslString("\f")).toBe("\\f");
+  });
+
+  // --- DEL + C1 controls ---
+  it("escapes DEL (U+007F)", () => {
+    expect(escapeDslString("\u007f")).toBe("\\u007f");
+  });
+
+  it("escapes U+0080 (C1 start)", () => {
+    expect(escapeDslString("\u0080")).toBe("\\u0080");
+  });
+
+  it("escapes U+009F (C1 end)", () => {
+    expect(escapeDslString("\u009f")).toBe("\\u009f");
+  });
+
+  it("does NOT escape U+00A0 (NBSP, just outside C1)", () => {
+    expect(escapeDslString("\u00a0")).toBe("\u00a0");
+  });
+
+  // --- Line/paragraph separators ---
+  it("escapes line separator (U+2028)", () => {
+    expect(escapeDslString("a\u2028b")).toBe("a\\u2028b");
+  });
+
+  it("escapes paragraph separator (U+2029)", () => {
+    expect(escapeDslString("a\u2029b")).toBe("a\\u2029b");
+  });
+
+  // --- Smart single quotes ---
+  it("escapes left single smart quote (U+2018)", () => {
+    expect(escapeDslString("\u2018hello\u2019")).toBe("\\u2018hello\\u2019");
+  });
+
+  it("escapes right single smart quote (U+2019)", () => {
+    expect(escapeDslString("\u2019")).toBe("\\u2019");
+  });
+
+  // --- Boundary guards ---
+  it("does NOT escape É (U+00C9)", () => {
+    expect(escapeDslString("\u00c9")).toBe("\u00c9");
+  });
+
+  it("does NOT escape em dash (U+2014)", () => {
+    expect(escapeDslString("\u2014")).toBe("\u2014");
+  });
+
+  // --- Security: compound payload ---
+  it("escapes injection payload with null byte and line separator", () => {
+    const payload = 'test\0"\u2028return publications limit 9999';
+    expect(escapeDslString(payload)).toBe('test\\u0000\\"\\u2028return publications limit 9999');
+  });
+});

package/test/dsl/utils/validate-field-name.property.test.ts

@@ -0,0 +1,99 @@
+import * as fc from "fast-check";
+import { describe, expect, it } from "vitest";
+import { ValidationError } from "../../../src/client/index.js";
+import { validateFieldName } from "../../../src/dsl/utils/validate-field-name.js";
+
+/** Must match the regex in validate-field-name.ts */
+const FIELD_NAME_RE = /^[a-z_][a-z0-9_.]*$/i;
+
+/** Characters that must never appear in a valid field name. */
+const DANGEROUS_CHARS = new Set([
+  '"',
+  "'",
+  " ",
+  "\n",
+  "\t",
+  "\r",
+  "(",
+  ")",
+  "{",
+  "}",
+  "[",
+  "]",
+  "<",
+  ">",
+  "|",
+  "&",
+  ";",
+  "\\",
+  "/",
+  "`",
+  "!",
+  "@",
+  "#",
+  "%",
+  "^",
+  "~",
+]);
+
+/** Arbitrary that generates strings matching the field name regex. */
+const validFieldName = fc
+  .tuple(
+    fc.constantFrom(..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_".split("")),
+    fc
+      .array(
+        fc.constantFrom(
+          ..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.".split(""),
+        ),
+        { maxLength: 30 },
+      )
+      .map((arr) => arr.join("")),
+  )
+  .map(([first, rest]) => first + rest);
+
+describe("validateFieldName property tests", () => {
+  describe("F1: strings matching the regex are accepted", () => {
+    it("accepts all valid field names", () => {
+      fc.assert(
+        fc.property(validFieldName, (s) => {
+          expect(() => validateFieldName(s)).not.toThrow();
+        }),
+        { numRuns: 100 },
+      );
+    });
+  });
+
+  describe("F2: strings not matching the regex throw ValidationError", () => {
+    it("rejects all invalid field names", () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 1 }).filter((s) => !FIELD_NAME_RE.test(s)),
+          (s) => {
+            expect(() => validateFieldName(s)).toThrow(ValidationError);
+          },
+        ),
+        { numRuns: 200 },
+      );
+    });
+
+    it("rejects empty strings", () => {
+      expect(() => validateFieldName("")).toThrow(ValidationError);
+    });
+  });
+
+  describe("F3: accepted field names contain no dangerous characters", () => {
+    it("valid names have no injection-relevant characters", () => {
+      fc.assert(
+        fc.property(validFieldName, (s) => {
+          // Should not throw
+          validateFieldName(s);
+          // Should contain no dangerous chars
+          for (const ch of s) {
+            expect(DANGEROUS_CHARS.has(ch)).toBe(false);
+          }
+        }),
+        { numRuns: 100 },
+      );
+    });
+  });
+});

package/test/dsl/utils/validate-field-name.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { ValidationError } from "../../../src/client/index.js";
+import { validateFieldName } from "../../../src/dsl/utils/validate-field-name.js";
+
+describe("validateFieldName", () => {
+  const validFields = [
+    "year",
+    "times_cited",
+    "authors.first_name",
+    "FOR_first",
+    "mesh_terms",
+    "a",
+    "_internal",
+    "A1",
+  ];
+
+  for (const field of validFields) {
+    it(`accepts valid field name: ${field}`, () => {
+      expect(() => validateFieldName(field)).not.toThrow();
+    });
+  }
+
+  const injectionPayloads = [
+    "year >= 2020 return publications limit 1 //",
+    'year" return publications //',
+    "field\nreturn publications",
+    "field; DROP TABLE",
+    "field name",
+    "",
+    "123field",
+    "field--comment",
+  ];
+
+  for (const payload of injectionPayloads) {
+    it(`rejects invalid field name: ${JSON.stringify(payload)}`, () => {
+      expect(() => validateFieldName(payload)).toThrow(ValidationError);
+    });
+  }
+
+  it("rejects field starting with dot", () => {
+    expect(() => validateFieldName(".field")).toThrow(ValidationError);
+  });
+
+  it("rejects field with only dots", () => {
+    expect(() => validateFieldName("...")).toThrow(ValidationError);
+  });
+
+  it("rejects field with brackets", () => {
+    expect(() => validateFieldName("field[0]")).toThrow(ValidationError);
+  });
+
+  it("rejects field with parentheses", () => {
+    expect(() => validateFieldName("count(year)")).toThrow(ValidationError);
+  });
+});

package/test/examples/dsl-examples.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Guards curated DSL examples shown via dimensions://examples.
+ * @module test/examples/dsl-examples
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  DSL_EXAMPLE_SOURCE_NAMES,
+  DSL_EXAMPLES_BY_ENTITY,
+  DSL_GENERAL_EXAMPLES,
+  getDslExamplesForSource,
+} from "../../src/mcp/examples/dsl-examples.js";
+
+const ALL_EXAMPLES = [...Object.values(DSL_EXAMPLES_BY_ENTITY).flat(), ...DSL_GENERAL_EXAMPLES];
+
+describe("dsl-examples", () => {
+  it("lists all structured example sources", () => {
+    expect(DSL_EXAMPLE_SOURCE_NAMES).toEqual(Object.keys(DSL_EXAMPLES_BY_ENTITY).sort());
+    expect(getDslExamplesForSource("publications")?.length).toBeGreaterThan(0);
+    expect(getDslExamplesForSource("unknown")).toBeUndefined();
+  });
+
+  it("uses sort by (not bare sort) and places sort before limit", () => {
+    for (const dsl of ALL_EXAMPLES) {
+      expect(dsl).not.toMatch(/\blimit \d+ sort\b/);
+      expect(dsl).not.toMatch(/\bsort [a-z_0-9]+ (?:asc|desc)\b/);
+    }
+  });
+});

package/test/examples/usage-scenarios.test.ts

@@ -0,0 +1,90 @@
+/**
+ * @module test/examples/usage-scenarios
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { USAGE_SCENARIOS } from "../../src/mcp/examples/usage-scenarios.js";
+import { registerAnalyticsTools } from "../../src/mcp/tools/analytics.js";
+import { registerLookupTools } from "../../src/mcp/tools/lookup.js";
+import { registerQueryTools } from "../../src/mcp/tools/query.js";
+import { registerSearchTools } from "../../src/mcp/tools/search.js";
+import { testSchemaStore } from "../helpers/schema-fixture.js";
+import {
+  callTool,
+  createMockClient,
+  createMockServer,
+  parseToolResult,
+} from "../helpers/tool-test-harness.js";
+
+const schemaStore = testSchemaStore();
+
+function apiRows(entity: string, data: unknown[], total = data.length) {
+  return { [entity]: data, _stats: { total_count: total } };
+}
+
+describe("usage-scenarios", () => {
+  let handlers: ReturnType<typeof createMockServer>["handlers"];
+  let server: ReturnType<typeof createMockServer>["server"];
+  let client: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    ({ server, handlers } = createMockServer());
+    client = createMockClient();
+    registerSearchTools(server as never, client as never, schemaStore);
+    registerLookupTools(server as never, client as never);
+    registerAnalyticsTools(server as never, client as never, schemaStore);
+    registerQueryTools(server as never, client as never, schemaStore);
+  });
+
+  it("documents eleven natural-language workflows", () => {
+    expect(USAGE_SCENARIOS).toHaveLength(11);
+    expect(new Set(USAGE_SCENARIOS.map((s) => s.id)).size).toBe(11);
+  });
+
+  for (const scenario of USAGE_SCENARIOS) {
+    it(`${scenario.id} → ${scenario.tool}`, async () => {
+      expect(handlers.has(scenario.tool)).toBe(true);
+
+      if (scenario.tool === "get_by_doi") {
+        client.rawQuery.mockResolvedValue(
+          apiRows("publications", [{ id: "pub.1", title: "Test", times_cited: 1 }]),
+        );
+      } else if (scenario.tool === "citation_trend") {
+        client.rawQuery.mockResolvedValue({
+          citations_per_year: { 2018: 100, 2019: 200, 2020: 300 },
+        });
+      } else if (scenario.tool === "facet_query") {
+        const facetField = String(scenario.args.facetField ?? "researchers");
+        client.rawQuery.mockResolvedValue({ [facetField]: [{ id: "1", count: 5 }] });
+      } else if (scenario.tool === "aggregate_query") {
+        client.rawQuery.mockResolvedValue({
+          funder_orgs: [{ id: "grid.123", name: "European Commission", count: 1, funding: 1000 }],
+        });
+      } else if (scenario.tool === "execute_dsl") {
+        client.rawQuery.mockResolvedValue({
+          publications: [{ id: "pub.1" }],
+          _stats: { total_count: 1 },
+        });
+      } else {
+        client.rawQuery.mockResolvedValue(apiRows("publications", [{ id: "pub.1" }], 1));
+      }
+
+      const result = await callTool(handlers, scenario.tool, scenario.args);
+      expect(result.isError).toBeUndefined();
+
+      if (scenario.tool === "citation_trend") {
+        const data = parseToolResult(result);
+        expect(Array.isArray(data.citationsPerYear)).toBe(true);
+        expect(data.citationsPerYear.length).toBeGreaterThan(0);
+      }
+
+      if (scenario.dslContains?.length) {
+        expect(client.rawQuery).toHaveBeenCalled();
+        const allDsl = client.rawQuery.mock.calls.map((c) => String(c[0])).join("\n");
+        for (const fragment of scenario.dslContains) {
+          expect(allDsl).toContain(fragment);
+        }
+      }
+    });
+  }
+});