@workglow/test-contract 0.6.1

package/dist/web-search.js

@@ -0,0 +1,560 @@
+// src/web-search/assertions/capabilityAgreement.ts
+import { unhonorableOptions, WebSearchTask } from "@workglow/web-search";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+// src/web-search/fixtures.ts
+import { WebSearchProviderRegistry } from "@workglow/web-search";
+var PROBE_QUERY = "transformer architecture";
+function decoyProvider(name, onSearch) {
+  return {
+    name,
+    endpoint: `https://${name}.invalid`,
+    acceptsCredentialKey: true,
+    capabilities: {
+      answer: true,
+      content: true,
+      domainFilter: "native",
+      dateFilter: true,
+      maxResultsCap: undefined
+    },
+    search: async (request) => {
+      onSearch?.(request);
+      return {
+        results: [{ title: "decoy", url: `https://${name}.invalid/a` }],
+        query: request.query
+      };
+    }
+  };
+}
+function registerOnly(harness) {
+  WebSearchProviderRegistry.clear();
+  WebSearchProviderRegistry.register(harness.provider);
+}
+function domainRoutes(provider) {
+  const capabilities = provider.capabilities;
+  return {
+    include: capabilities.domainFilter,
+    exclude: capabilities.excludeDomainFilter ?? capabilities.domainFilter
+  };
+}
+function decodeLoosely(text) {
+  try {
+    return decodeURIComponent(text.replace(/\+/g, " "));
+  } catch {
+    return text;
+  }
+}
+function sentText(harness) {
+  const raw = harness.sent().join(`
+`);
+  return `${raw}
+${decodeLoosely(raw)}`;
+}
+
+// src/web-search/assertions/capabilityAgreement.ts
+function probesFor(domain) {
+  return [
+    { label: "includeDomains", request: { includeDomains: [domain] } },
+    { label: "excludeDomains", request: { excludeDomains: [domain] } },
+    {
+      label: "includeDomains with excludeDomains",
+      request: { includeDomains: [domain], excludeDomains: ["elsewhere.example"] }
+    },
+    { label: "dateRange", request: { dateRange: { start: "2024-01-01", end: "2024-12-31" } } },
+    { label: "includeAnswer", request: { includeAnswer: true } },
+    { label: "includeContent", request: { includeContent: true } }
+  ];
+}
+function capabilityAgreementBlock(opts) {
+  const domain = opts.sampleDomain ?? "example.com";
+  const probes = probesFor(domain);
+  describe("capability agreement", () => {
+    let harness;
+    beforeEach(async () => {
+      harness = await opts.createHarness({ resultCount: 2 });
+      registerOnly(harness);
+    });
+    afterEach(() => harness.dispose());
+    it("probes every option the capability check can refuse", () => {
+      const everything = {
+        answer: false,
+        content: false,
+        domainFilter: false,
+        excludeDomainFilter: false,
+        exclusiveDomainDirections: true,
+        dateFilter: false,
+        maxResultsCap: undefined
+      };
+      const reachable = new Set;
+      for (const probe of probes) {
+        for (const gap of unhonorableOptions(everything, {
+          query: PROBE_QUERY,
+          ...probe.request
+        })) {
+          reachable.add(gap);
+        }
+      }
+      for (const gap of unhonorableOptions({ ...everything, domainFilter: "native", excludeDomainFilter: "native" }, { query: PROBE_QUERY, includeDomains: [domain], excludeDomains: ["elsewhere.example"] })) {
+        reachable.add(gap);
+      }
+      expect([...reachable].sort()).toEqual(probes.map((p) => p.label).sort());
+    }, opts.timeout);
+    for (const probe of probes) {
+      it(`agrees with its own record about ${probe.label}`, async () => {
+        const declared = unhonorableOptions(harness.provider.capabilities, {
+          query: PROBE_QUERY,
+          ...probe.request
+        });
+        const run = new WebSearchTask().run({
+          query: PROBE_QUERY,
+          provider: harness.provider.name,
+          ...probe.request
+        });
+        if (declared.length > 0) {
+          await expect(run).rejects.toThrow(new RegExp(declared.map((g) => g.replace(/\s/g, "\\s")).join("|")));
+          expect(harness.sent()).toEqual([]);
+        } else {
+          const output = await run;
+          expect(harness.sent().length).toBeGreaterThan(0);
+          if (probe.request.includeAnswer === true) {
+            expect(output.answer).toBeTruthy();
+          }
+          if (probe.request.includeContent === true) {
+            expect(output.results.some((result) => Boolean(result.content))).toBe(true);
+          }
+        }
+      }, opts.timeout);
+    }
+  });
+}
+// src/web-search/assertions/credentialNaming.ts
+import { WebSearchProviderRegistry as WebSearchProviderRegistry2, WebSearchTask as WebSearchTask2 } from "@workglow/web-search";
+import { afterEach as afterEach2, beforeEach as beforeEach2, describe as describe2, expect as expect2, it as it2 } from "vitest";
+var DECOY = "conformance-decoy";
+var SECRET_KEY = "conformance-key-for-the-decoy";
+function credentialNamingBlock(opts) {
+  describe2("credential naming", () => {
+    let harness;
+    beforeEach2(async () => {
+      harness = await opts.createHarness({ resultCount: 2 });
+      registerOnly(harness);
+    });
+    afterEach2(() => {
+      harness.dispose();
+      WebSearchProviderRegistry2.clear();
+    });
+    it2("refuses a bare credential_key under auto", async () => {
+      await expect2(new WebSearchTask2().run({
+        query: PROBE_QUERY,
+        provider: "auto",
+        credential_key: SECRET_KEY
+      })).rejects.toThrow(/credential_key.*auto|auto.*credential_key/s);
+      expect2(harness.sent()).toEqual([]);
+    }, opts.timeout);
+    it2("never sends a key named for another provider", async () => {
+      let decoyRan = false;
+      WebSearchProviderRegistry2.register(decoyProvider(DECOY, () => {
+        decoyRan = true;
+      }));
+      await new WebSearchTask2().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        credential_keys: { [DECOY]: SECRET_KEY }
+      });
+      expect2(decoyRan).toBe(false);
+      expect2(sentText(harness)).not.toContain(SECRET_KEY);
+    }, opts.timeout);
+    it2("refuses a key named for a provider that is not registered", async () => {
+      await expect2(new WebSearchTask2().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        credential_keys: { "not-a-provider": SECRET_KEY }
+      })).rejects.toThrow(/not a .*registered provider/s);
+      expect2(harness.sent()).toEqual([]);
+    }, opts.timeout);
+    it2("says so when this provider never receives a credential key", async () => {
+      const run = new WebSearchTask2().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        credential_keys: { [harness.provider.name]: SECRET_KEY }
+      });
+      if (harness.provider.acceptsCredentialKey) {
+        await expect2(run).resolves.toBeDefined();
+        return;
+      }
+      await expect2(run).rejects.toThrow(/never receives a credential-store key/);
+      expect2(harness.sent()).toEqual([]);
+    }, opts.timeout);
+    it2("prefers a provider a key is named for when routing", async () => {
+      let decoyRan = false;
+      WebSearchProviderRegistry2.register(decoyProvider(DECOY, () => {
+        decoyRan = true;
+      }));
+      const out = await new WebSearchTask2().run({
+        query: PROBE_QUERY,
+        provider: "auto",
+        credential_keys: { [DECOY]: SECRET_KEY }
+      });
+      expect2(out.provider).toBe(DECOY);
+      expect2(decoyRan).toBe(true);
+      expect2(harness.sent()).toEqual([]);
+    }, opts.timeout);
+  });
+}
+// src/web-search/assertions/dateFiltering.ts
+import { WebSearchTask as WebSearchTask3 } from "@workglow/web-search";
+import { afterEach as afterEach3, describe as describe3, expect as expect3, it as it3 } from "vitest";
+function datesIn(text) {
+  return [...new Set(text.match(/\d{4}-\d{2}-\d{2}/g) ?? [])];
+}
+var RANGES = [
+  { label: "a closed range", value: { start: "2024-01-01", end: "2024-06-30" } },
+  { label: "a range open at the start", value: { end: "2024-06-30" } },
+  { label: "a range open at the end", value: { start: "2024-01-01" } }
+];
+function dateFilteringBlock(opts) {
+  describe3("date filtering", () => {
+    let harness;
+    afterEach3(() => harness?.dispose());
+    for (const range of RANGES) {
+      it3(`never emulates ${range.label}`, async () => {
+        harness = await opts.createHarness({ resultCount: 3 });
+        registerOnly(harness);
+        const run = new WebSearchTask3().run({
+          query: PROBE_QUERY,
+          provider: harness.provider.name,
+          dateRange: { ...range.value }
+        });
+        if (!harness.provider.capabilities.dateFilter) {
+          await expect3(run).rejects.toThrow(/dateRange/);
+          expect3(harness.sent()).toEqual([]);
+          return;
+        }
+        await expect3(run).resolves.toBeDefined();
+        const withRange = sentText(harness);
+        harness.dispose();
+        const plain = await opts.createHarness({ resultCount: 3 });
+        registerOnly(plain);
+        try {
+          await new WebSearchTask3().run({
+            query: PROBE_QUERY,
+            provider: plain.provider.name
+          });
+          expect3(withRange).not.toEqual(sentText(plain));
+        } finally {
+          plain.dispose();
+        }
+      }, opts.timeout);
+    }
+    it3("fills the open end of a half-open range rather than sending it half", async () => {
+      harness = await opts.createHarness({ resultCount: 3 });
+      registerOnly(harness);
+      if (!harness.provider.capabilities.dateFilter)
+        return;
+      await new WebSearchTask3().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        dateRange: { start: "2024-01-01" }
+      });
+      const openEnded = datesIn(sentText(harness));
+      expect3(openEnded).toContain("2024-01-01");
+      if (!opts.fillsOpenDateBounds) {
+        return;
+      }
+      expect3(openEnded.length).toBeGreaterThanOrEqual(2);
+    }, opts.timeout);
+    it3("fills the open start of a half-open range too", async () => {
+      harness = await opts.createHarness({ resultCount: 3 });
+      registerOnly(harness);
+      if (!harness.provider.capabilities.dateFilter)
+        return;
+      await new WebSearchTask3().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        dateRange: { end: "2024-06-30" }
+      });
+      const openStart = datesIn(sentText(harness));
+      expect3(openStart).toContain("2024-06-30");
+      if (!opts.fillsOpenDateBounds)
+        return;
+      expect3(openStart.length).toBeGreaterThanOrEqual(2);
+    }, opts.timeout);
+  });
+}
+// src/web-search/assertions/domainNormalization.ts
+import { WebSearchTask as WebSearchTask4 } from "@workglow/web-search";
+import { afterEach as afterEach4, beforeEach as beforeEach3, describe as describe4, expect as expect4, it as it4 } from "vitest";
+var SPELLINGS = ["https://Example.COM/", "www.example.com", "EXAMPLE.com", "example.com/"];
+var UNUSABLE = ["", "   ", "a.com b.com", "(example.com)", 'ex"ample.com', "it's.com"];
+function domainNormalizationBlock(opts) {
+  describe4("domain normalization", () => {
+    let harness;
+    beforeEach3(async () => {
+      harness = await opts.createHarness({ resultCount: 2 });
+      registerOnly(harness);
+    });
+    afterEach4(() => harness.dispose());
+    const routes = () => domainRoutes(harness.provider);
+    it4("reduces every spelling of one host to the same request", async () => {
+      if (routes().include === false)
+        return;
+      const sentFor = async (domain) => {
+        const local = await opts.createHarness({ resultCount: 2 });
+        registerOnly(local);
+        try {
+          await new WebSearchTask4().run({
+            query: PROBE_QUERY,
+            provider: local.provider.name,
+            includeDomains: [domain]
+          });
+          return sentText(local);
+        } finally {
+          local.dispose();
+        }
+      };
+      const first = await sentFor(SPELLINGS[0]);
+      for (const spelling of SPELLINGS.slice(1)) {
+        expect4(await sentFor(spelling)).toEqual(first);
+      }
+    }, opts.timeout);
+    it4("carries the restriction to the wire rather than dropping it", async () => {
+      if (routes().include === false)
+        return;
+      const plain = await opts.createHarness({ resultCount: 2 });
+      registerOnly(plain);
+      await new WebSearchTask4().run({ query: PROBE_QUERY, provider: plain.provider.name });
+      const withoutFilter = sentText(plain);
+      plain.dispose();
+      registerOnly(harness);
+      await new WebSearchTask4().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        includeDomains: ["example.com"]
+      });
+      expect4(sentText(harness)).not.toEqual(withoutFilter);
+      expect4(sentText(harness)).toContain("example.com");
+    }, opts.timeout);
+    it4("carries an exclude restriction to the wire rather than dropping it", async () => {
+      if (routes().exclude === false)
+        return;
+      const plain = await opts.createHarness({ resultCount: 2 });
+      registerOnly(plain);
+      await new WebSearchTask4().run({ query: PROBE_QUERY, provider: plain.provider.name });
+      const withoutFilter = sentText(plain);
+      plain.dispose();
+      registerOnly(harness);
+      await new WebSearchTask4().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        excludeDomains: ["blocked.example"]
+      });
+      expect4(sentText(harness)).not.toEqual(withoutFilter);
+      expect4(sentText(harness)).toContain("blocked.example");
+    }, opts.timeout);
+    for (const entry of UNUSABLE) {
+      it4(`refuses includeDomains ${JSON.stringify(entry)} before the call`, async () => {
+        await expect4(new WebSearchTask4().run({
+          query: PROBE_QUERY,
+          provider: harness.provider.name,
+          includeDomains: [entry]
+        })).rejects.toThrow(/names no domain|name no domain/);
+        expect4(harness.sent()).toEqual([]);
+      }, opts.timeout);
+      it4(`refuses excludeDomains ${JSON.stringify(entry)} before the call`, async () => {
+        await expect4(new WebSearchTask4().run({
+          query: PROBE_QUERY,
+          provider: harness.provider.name,
+          excludeDomains: [entry]
+        })).rejects.toThrow(/names no domain|name no domain/);
+        expect4(harness.sent()).toEqual([]);
+      }, opts.timeout);
+    }
+    it4("refuses a bad entry even beside good ones", async () => {
+      await expect4(new WebSearchTask4().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        includeDomains: ["good.example", "a.com b.com", "also-good.example"]
+      })).rejects.toThrow(/names no domain/);
+      expect4(harness.sent()).toEqual([]);
+    }, opts.timeout);
+  });
+}
+// src/web-search/assertions/maxResultsCeiling.ts
+import { WebSearchTask as WebSearchTask5 } from "@workglow/web-search";
+import { afterEach as afterEach5, beforeEach as beforeEach4, describe as describe5, expect as expect5, it as it5 } from "vitest";
+function maxResultsCeilingBlock(opts) {
+  describe5("maxResults ceiling", () => {
+    let harness;
+    afterEach5(() => harness?.dispose());
+    beforeEach4(() => {});
+    it5("never returns more results than asked for", async () => {
+      harness = await opts.createHarness({ resultCount: 9 });
+      registerOnly(harness);
+      const out = await new WebSearchTask5().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        maxResults: 3
+      });
+      expect5(out.results.length).toBeLessThanOrEqual(3);
+      expect5(out.count).toBe(out.results.length);
+    }, opts.timeout);
+    it5("clamps a value over the provider's cap rather than refusing it", async () => {
+      harness = await opts.createHarness({ resultCount: 4 });
+      registerOnly(harness);
+      const cap = harness.provider.capabilities.maxResultsCap;
+      const asked = (cap ?? 20) + 500;
+      const out = await new WebSearchTask5().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        maxResults: asked
+      });
+      expect5(out.results.length).toBeLessThanOrEqual(cap ?? asked);
+    }, opts.timeout);
+    it5("returns what it has when fewer results exist than asked for", async () => {
+      harness = await opts.createHarness({ resultCount: 2 });
+      registerOnly(harness);
+      const out = await new WebSearchTask5().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        maxResults: 8
+      });
+      expect5(out.results).toHaveLength(2);
+    }, opts.timeout);
+    it5("reports count as the number of results it actually returned", async () => {
+      harness = await opts.createHarness({ resultCount: 6 });
+      registerOnly(harness);
+      const out = await new WebSearchTask5().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        maxResults: 2
+      });
+      expect5(out.count).toBe(out.results.length);
+    }, opts.timeout);
+  });
+}
+// src/web-search/assertions/reportedQuery.ts
+import { WebSearchTask as WebSearchTask6 } from "@workglow/web-search";
+import { afterEach as afterEach6, beforeEach as beforeEach5, describe as describe6, expect as expect6, it as it6 } from "vitest";
+function reportedQueryBlock(opts) {
+  describe6("reported query and provider", () => {
+    let harness;
+    beforeEach5(async () => {
+      harness = await opts.createHarness({ resultCount: 3 });
+      registerOnly(harness);
+    });
+    afterEach6(() => harness.dispose());
+    it6("reports the provider that ran when it was pinned", async () => {
+      const out = await new WebSearchTask6().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name
+      });
+      expect6(out.provider).toBe(harness.provider.name);
+    }, opts.timeout);
+    it6("reports the provider that ran when routing chose it", async () => {
+      const out = await new WebSearchTask6().run({ query: PROBE_QUERY, provider: "auto" });
+      expect6(out.provider).toBe(harness.provider.name);
+    }, opts.timeout);
+    it6("reports the unmodified query when nothing rewrote it", async () => {
+      const out = await new WebSearchTask6().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name
+      });
+      expect6(out.query).toBe(PROBE_QUERY);
+    }, opts.timeout);
+    it6("reports the rewritten query when a domain restriction moved into it", async () => {
+      const routes = domainRoutes(harness.provider);
+      if (routes.include !== "query-operator")
+        return;
+      const out = await new WebSearchTask6().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        includeDomains: ["example.com"]
+      });
+      expect6(out.query).toContain("site:example.com");
+      expect6(out.query).not.toBe(PROBE_QUERY);
+      expect6(sentText(harness)).toContain("site:example.com");
+    }, opts.timeout);
+    it6("leaves the query alone when the restriction travels as a list", async () => {
+      const routes = domainRoutes(harness.provider);
+      if (routes.include !== "native")
+        return;
+      const out = await new WebSearchTask6().run({
+        query: PROBE_QUERY,
+        provider: harness.provider.name,
+        includeDomains: ["example.com"]
+      });
+      expect6(out.query).toBe(PROBE_QUERY);
+    }, opts.timeout);
+    it6("always reports results and a count, even with nothing to report", async () => {
+      const empty = await opts.createHarness({ resultCount: 0 });
+      registerOnly(empty);
+      try {
+        const out = await new WebSearchTask6().run({
+          query: PROBE_QUERY,
+          provider: empty.provider.name
+        });
+        expect6(Array.isArray(out.results)).toBe(true);
+        expect6(out.count).toBe(0);
+        expect6(out.provider).toBe(empty.provider.name);
+      } finally {
+        empty.dispose();
+      }
+    }, opts.timeout);
+  });
+}
+// src/web-search/assertions/signalThreading.ts
+import { afterEach as afterEach7, beforeEach as beforeEach6, describe as describe7, expect as expect7, it as it7 } from "vitest";
+function signalThreadingBlock(opts) {
+  describe7.skipIf(!opts.signalReachesTransport)("signal threading", () => {
+    let harness;
+    beforeEach6(async () => {
+      harness = await opts.createHarness({ resultCount: 2 });
+      registerOnly(harness);
+    });
+    afterEach7(() => harness.dispose());
+    it7("hands the run's signal to the outbound call", async () => {
+      const controller = new AbortController;
+      await harness.search({ query: PROBE_QUERY }, controller.signal);
+      const signals = harness.signals();
+      expect7(signals.length).toBeGreaterThan(0);
+      for (const signal of signals) {
+        expect7(signal).toBeDefined();
+        expect7(signal?.aborted).toBe(false);
+      }
+      controller.abort();
+      for (const signal of signals) {
+        expect7(signal?.aborted).toBe(true);
+      }
+    }, opts.timeout);
+  });
+}
+// src/web-search/runWebSearchProviderConformance.ts
+import { describe as describe8 } from "vitest";
+function runWebSearchProviderConformance(opts) {
+  describe8.skipIf(opts.skip)(`Web search provider contract: ${opts.name}`, () => {
+    capabilityAgreementBlock(opts);
+    maxResultsCeilingBlock(opts);
+    domainNormalizationBlock(opts);
+    dateFilteringBlock(opts);
+    reportedQueryBlock(opts);
+    signalThreadingBlock(opts);
+    credentialNamingBlock(opts);
+  });
+}
+export {
+  PROBE_QUERY,
+  capabilityAgreementBlock,
+  credentialNamingBlock,
+  dateFilteringBlock,
+  decoyProvider,
+  domainNormalizationBlock,
+  domainRoutes,
+  maxResultsCeilingBlock,
+  registerOnly,
+  reportedQueryBlock,
+  runWebSearchProviderConformance,
+  sentText,
+  signalThreadingBlock
+};
+
+//# debugId=C4B5C15DB8F13A3964756E2164756E21