@ncukondo/search-hub 0.12.1 → 0.13.0

package/dist/query/json-schema.d.ts

@@ -0,0 +1,3 @@
+/** Generate a JSON Schema from the query file Zod schema. */
+export declare function generateQueryJSONSchema(): Record<string, unknown>;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/query/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/query/json-schema.ts"],"names":[],"mappings":"AAsEA,6DAA6D;AAC7D,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIjE"}

package/dist/query/json-schema.js

@@ -0,0 +1,48 @@
+import * as z from "zod";
+import { publicationTypeFilterSchema, operatorSchema, fieldTypeSchema } from "./validator.js";
+const filtersInputSchema = z.object({
+  year_from: z.number().int().optional(),
+  year_to: z.number().int().optional(),
+  language: z.array(z.string()).optional(),
+  publication_types: publicationTypeFilterSchema.optional()
+}).optional();
+const overrideBlockInputSchema = z.object({
+  filters: filtersInputSchema,
+  categories: z.array(z.string()).optional(),
+  source_types: z.array(z.string()).optional()
+}).optional();
+const termBlockInputSchema = z.object({
+  keywords: z.array(z.string()).min(1).optional(),
+  mesh: z.array(z.string()).optional(),
+  emtree: z.array(z.string()).optional(),
+  eric: z.array(z.string()).optional(),
+  exclude: z.array(z.string()).optional()
+});
+const queryBlockInputSchema = z.object({
+  field: fieldTypeSchema,
+  terms: termBlockInputSchema,
+  operator: operatorSchema
+});
+const queryFileInputSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  query: z.array(queryBlockInputSchema).min(1),
+  filters: filtersInputSchema,
+  overrides: z.object({
+    pubmed: overrideBlockInputSchema,
+    scopus: overrideBlockInputSchema,
+    eric: overrideBlockInputSchema,
+    arxiv: overrideBlockInputSchema,
+    wos: overrideBlockInputSchema,
+    embase: overrideBlockInputSchema
+  }).optional()
+});
+function generateQueryJSONSchema() {
+  return z.toJSONSchema(queryFileInputSchema, {
+    target: "draft-2020-12"
+  });
+}
+export {
+  generateQueryJSONSchema
+};
+//# sourceMappingURL=json-schema.js.map

package/dist/query/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sources":["../../src/query/json-schema.ts"],"sourcesContent":["/**\n * JSON Schema generation for query YAML files.\n *\n * Defines an input-only schema (without transforms) that mirrors the structure\n * of queryFileSchema from validator.ts. This is necessary because Zod v4's\n * z.toJSONSchema() cannot handle .transform() calls.\n *\n * The generated JSON Schema enables editor autocompletion and validation\n * via the yaml-language-server $schema comment.\n */\nimport * as z from 'zod';\nimport {\n  fieldTypeSchema,\n  operatorSchema,\n  publicationTypeFilterSchema,\n} from './validator.js';\n\n/** Filters input schema (without transform) */\nconst filtersInputSchema = z\n  .object({\n    year_from: z.number().int().optional(),\n    year_to: z.number().int().optional(),\n    language: z.array(z.string()).optional(),\n    publication_types: publicationTypeFilterSchema.optional(),\n  })\n  .optional();\n\n/** Override block input schema (without transform) */\nconst overrideBlockInputSchema = z\n  .object({\n    filters: filtersInputSchema,\n    categories: z.array(z.string()).optional(),\n    source_types: z.array(z.string()).optional(),\n  })\n  .optional();\n\n/** Term block input schema (without refine) */\nconst termBlockInputSchema = z.object({\n  keywords: z.array(z.string()).min(1).optional(),\n  mesh: z.array(z.string()).optional(),\n  emtree: z.array(z.string()).optional(),\n  eric: z.array(z.string()).optional(),\n  exclude: z.array(z.string()).optional(),\n});\n\n/** Query block input schema */\nconst queryBlockInputSchema = z.object({\n  field: fieldTypeSchema,\n  terms: termBlockInputSchema,\n  operator: operatorSchema,\n});\n\n/** Query file input schema (without transform) - mirrors queryFileSchema input */\nconst queryFileInputSchema = z.object({\n  name: z.string().min(1),\n  description: z.string().optional(),\n  query: z.array(queryBlockInputSchema).min(1),\n  filters: filtersInputSchema,\n  overrides: z\n    .object({\n      pubmed: overrideBlockInputSchema,\n      scopus: overrideBlockInputSchema,\n      eric: overrideBlockInputSchema,\n      arxiv: overrideBlockInputSchema,\n      wos: overrideBlockInputSchema,\n      embase: overrideBlockInputSchema,\n    })\n    .optional(),\n});\n\n/** Generate a JSON Schema from the query file Zod schema. */\nexport function generateQueryJSONSchema(): Record<string, unknown> {\n  return z.toJSONSchema(queryFileInputSchema, {\n    target: 'draft-2020-12',\n  });\n}\n"],"names":[],"mappings":";;AAkBA,MAAM,qBAAqB,EACxB,OAAO;AAAA,EACN,WAAW,EAAE,OAAA,EAAS,IAAA,EAAM,SAAA;AAAA,EAC5B,SAAS,EAAE,OAAA,EAAS,IAAA,EAAM,SAAA;AAAA,EAC1B,UAAU,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AAAA,EAC9B,mBAAmB,4BAA4B,SAAA;AACjD,CAAC,EACA,SAAA;AAGH,MAAM,2BAA2B,EAC9B,OAAO;AAAA,EACN,SAAS;AAAA,EACT,YAAY,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AAAA,EAChC,cAAc,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AACpC,CAAC,EACA,SAAA;AAGH,MAAM,uBAAuB,EAAE,OAAO;AAAA,EACpC,UAAU,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,IAAI,CAAC,EAAE,SAAA;AAAA,EACrC,MAAM,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AAAA,EAC1B,QAAQ,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AAAA,EAC5B,MAAM,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AAAA,EAC1B,SAAS,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AAC/B,CAAC;AAGD,MAAM,wBAAwB,EAAE,OAAO;AAAA,EACrC,OAAO;AAAA,EACP,OAAO;AAAA,EACP,UAAU;AACZ,CAAC;AAGD,MAAM,uBAAuB,EAAE,OAAO;AAAA,EACpC,MAAM,EAAE,SAAS,IAAI,CAAC;AAAA,EACtB,aAAa,EAAE,OAAA,EAAS,SAAA;AAAA,EACxB,OAAO,EAAE,MAAM,qBAAqB,EAAE,IAAI,CAAC;AAAA,EAC3C,SAAS;AAAA,EACT,WAAW,EACR,OAAO;AAAA,IACN,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,MAAM;AAAA,IACN,OAAO;AAAA,IACP,KAAK;AAAA,IACL,QAAQ;AAAA,EAAA,CACT,EACA,SAAA;AACL,CAAC;AAGM,SAAS,0BAAmD;AACjE,SAAO,EAAE,aAAa,sBAAsB;AAAA,IAC1C,QAAQ;AAAA,EAAA,CACT;AACH;"}

package/dist/query/mesh-lookup.d.ts

@@ -0,0 +1,47 @@
+import { RateLimiter } from '../providers/base/rate-limiter.js';
+import { VocabCache } from './vocab-cache.js';
+/**
+ * Result of a MeSH term lookup.
+ */
+export interface MeSHLookupResult {
+    /** The term that was looked up */
+    term: string;
+    /** Whether the term was found as a valid MeSH heading */
+    found: boolean;
+    /** Suggested terms if the lookup term was not found */
+    suggestions?: string[];
+}
+/**
+ * Client for the NLM MeSH Lookup API.
+ */
+export declare class MeSHLookupClient {
+    private readonly rateLimiter;
+    private readonly timeoutMs;
+    private readonly cache;
+    constructor(options?: {
+        rateLimiter?: RateLimiter;
+        timeoutMs?: number;
+        cache?: VocabCache;
+    });
+    /**
+     * Look up a single MeSH term.
+     *
+     * Tries multiple match strategies in order:
+     * 1. exact — exact match
+     * 2. startsWith (full term) — prefix match
+     * 2b. startsWith (truncated) — suffix typo recovery (1-3 chars removed)
+     * 2c. startsWith (word1 + word2 prefix) — multi-word progressive prefix (max 3 calls)
+     * 3. contains (full term) — substring match
+     * 4. startsWith (first word, limit=25) — re-ranked by Levenshtein distance
+     *
+     * Returns on the first strategy that produces results.
+     * Results are cached when a VocabCache is provided.
+     */
+    lookupTerm(term: string): Promise<MeSHLookupResult>;
+    /**
+     * Look up multiple MeSH terms.
+     */
+    lookupTerms(terms: string[]): Promise<MeSHLookupResult[]>;
+    private fetchLookup;
+}
+//# sourceMappingURL=mesh-lookup.d.ts.map

package/dist/query/mesh-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-lookup.d.ts","sourceRoot":"","sources":["../../src/query/mesh-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAOD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;gBAEnC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,UAAU,CAAA;KAAE;IAM3F;;;;;;;;;;;;;OAaG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA4GzD;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAQjD,WAAW;CAoC1B"}

package/dist/query/mesh-lookup.js

@@ -0,0 +1,151 @@
+import { levenshteinDistance } from "../utils/levenshtein.js";
+const MESH_LOOKUP_BASE_URL = "https://id.nlm.nih.gov/mesh/lookup/term";
+const DEFAULT_TIMEOUT_MS = 1e4;
+class MeSHLookupClient {
+  rateLimiter;
+  timeoutMs;
+  cache;
+  constructor(options) {
+    this.rateLimiter = options?.rateLimiter;
+    this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.cache = options?.cache;
+  }
+  /**
+   * Look up a single MeSH term.
+   *
+   * Tries multiple match strategies in order:
+   * 1. exact — exact match
+   * 2. startsWith (full term) — prefix match
+   * 2b. startsWith (truncated) — suffix typo recovery (1-3 chars removed)
+   * 2c. startsWith (word1 + word2 prefix) — multi-word progressive prefix (max 3 calls)
+   * 3. contains (full term) — substring match
+   * 4. startsWith (first word, limit=25) — re-ranked by Levenshtein distance
+   *
+   * Returns on the first strategy that produces results.
+   * Results are cached when a VocabCache is provided.
+   */
+  async lookupTerm(term) {
+    if (this.cache) {
+      const cached = this.cache.get("mesh", term);
+      if (cached) {
+        return cached;
+      }
+    }
+    const exactResults = await this.fetchLookup(term, "exact", 1);
+    if (exactResults.length > 0) {
+      const result2 = { term, found: true };
+      this.cache?.set("mesh", term, result2);
+      return result2;
+    }
+    const startsWithResults = await this.fetchLookup(term, "startswith", 5);
+    if (startsWithResults.length > 0) {
+      const result2 = {
+        term,
+        found: false,
+        suggestions: startsWithResults.map((s) => s.label)
+      };
+      this.cache?.set("mesh", term, result2);
+      return result2;
+    }
+    if (term.length > 3) {
+      for (let len = term.length - 1; len >= Math.max(term.length - 3, 3); len--) {
+        const truncated = term.slice(0, len);
+        const truncatedResults = await this.fetchLookup(truncated, "startswith", 5);
+        if (truncatedResults.length > 0) {
+          const result2 = {
+            term,
+            found: false,
+            suggestions: truncatedResults.map((s) => s.label)
+          };
+          this.cache?.set("mesh", term, result2);
+          return result2;
+        }
+      }
+    }
+    const words = term.split(/\s+/);
+    if (words.length >= 2 && words[1].length > 3) {
+      const startN = Math.min(words[1].length - 4, words[1].length - 1);
+      const endN = 3;
+      let iterations = 0;
+      for (let n = startN; n >= endN && iterations < 3; n--, iterations++) {
+        const prefix = words[0] + " " + words[1].slice(0, n);
+        const prefixResults = await this.fetchLookup(prefix, "startswith", 5);
+        if (prefixResults.length > 0) {
+          const result2 = {
+            term,
+            found: false,
+            suggestions: prefixResults.map((s) => s.label)
+          };
+          this.cache?.set("mesh", term, result2);
+          return result2;
+        }
+      }
+    }
+    const containsResults = await this.fetchLookup(term, "contains", 5);
+    if (containsResults.length > 0) {
+      const result2 = {
+        term,
+        found: false,
+        suggestions: containsResults.map((s) => s.label)
+      };
+      this.cache?.set("mesh", term, result2);
+      return result2;
+    }
+    if (words.length > 1) {
+      const firstWord = words[0];
+      const firstWordResults = await this.fetchLookup(firstWord, "startswith", 25);
+      if (firstWordResults.length > 0) {
+        const ranked = firstWordResults.map((s) => ({
+          label: s.label,
+          distance: levenshteinDistance(term.toLowerCase(), s.label.toLowerCase())
+        })).sort((a, b) => a.distance - b.distance).slice(0, 5).map((s) => s.label);
+        const result2 = { term, found: false, suggestions: ranked };
+        this.cache?.set("mesh", term, result2);
+        return result2;
+      }
+    }
+    const result = { term, found: false };
+    this.cache?.set("mesh", term, result);
+    return result;
+  }
+  /**
+   * Look up multiple MeSH terms.
+   */
+  async lookupTerms(terms) {
+    const results = [];
+    for (const term of terms) {
+      results.push(await this.lookupTerm(term));
+    }
+    return results;
+  }
+  async fetchLookup(label, match, limit) {
+    if (this.rateLimiter) {
+      await this.rateLimiter.acquire();
+    }
+    const params = new URLSearchParams({
+      label,
+      match,
+      limit: String(limit)
+    });
+    const url = `${MESH_LOOKUP_BASE_URL}?${params.toString()}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`MeSH lookup failed: ${message}`);
+    }
+    if (!response.ok) {
+      throw new Error(
+        `MeSH lookup failed: HTTP ${response.status} ${response.statusText}`
+      );
+    }
+    return await response.json();
+  }
+}
+export {
+  MeSHLookupClient
+};
+//# sourceMappingURL=mesh-lookup.js.map

package/dist/query/mesh-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-lookup.js","sources":["../../src/query/mesh-lookup.ts"],"sourcesContent":["/**\n * MeSH Lookup API client.\n *\n * Validates MeSH (Medical Subject Headings) terms against the NLM MeSH Lookup API.\n * No API key required.\n *\n * API docs: https://id.nlm.nih.gov/mesh/lookup/term\n */\n\nimport type { RateLimiter } from '../providers/base/rate-limiter.js';\nimport type { VocabCache } from './vocab-cache.js';\nimport { levenshteinDistance } from '../utils/levenshtein.js';\n\nconst MESH_LOOKUP_BASE_URL = 'https://id.nlm.nih.gov/mesh/lookup/term';\nconst DEFAULT_TIMEOUT_MS = 10_000;\n\n/**\n * Result of a MeSH term lookup.\n */\nexport interface MeSHLookupResult {\n  /** The term that was looked up */\n  term: string;\n  /** Whether the term was found as a valid MeSH heading */\n  found: boolean;\n  /** Suggested terms if the lookup term was not found */\n  suggestions?: string[];\n}\n\ninterface MeSHApiEntry {\n  resource: string;\n  label: string;\n}\n\n/**\n * Client for the NLM MeSH Lookup API.\n */\nexport class MeSHLookupClient {\n  private readonly rateLimiter: RateLimiter | undefined;\n  private readonly timeoutMs: number;\n  private readonly cache: VocabCache | undefined;\n\n  constructor(options?: { rateLimiter?: RateLimiter; timeoutMs?: number; cache?: VocabCache }) {\n    this.rateLimiter = options?.rateLimiter;\n    this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.cache = options?.cache;\n  }\n\n  /**\n   * Look up a single MeSH term.\n   *\n   * Tries multiple match strategies in order:\n   * 1. exact — exact match\n   * 2. startsWith (full term) — prefix match\n   * 2b. startsWith (truncated) — suffix typo recovery (1-3 chars removed)\n   * 2c. startsWith (word1 + word2 prefix) — multi-word progressive prefix (max 3 calls)\n   * 3. contains (full term) — substring match\n   * 4. startsWith (first word, limit=25) — re-ranked by Levenshtein distance\n   *\n   * Returns on the first strategy that produces results.\n   * Results are cached when a VocabCache is provided.\n   */\n  async lookupTerm(term: string): Promise<MeSHLookupResult> {\n    // Check cache first\n    if (this.cache) {\n      const cached = this.cache.get('mesh', term);\n      if (cached) {\n        return cached;\n      }\n    }\n\n    // 1. Try exact match first\n    const exactResults = await this.fetchLookup(term, 'exact', 1);\n\n    if (exactResults.length > 0) {\n      const result: MeSHLookupResult = { term, found: true };\n      this.cache?.set('mesh', term, result);\n      return result;\n    }\n\n    // 2. Try startsWith (full term) for suggestions\n    const startsWithResults = await this.fetchLookup(term, 'startswith', 5);\n\n    if (startsWithResults.length > 0) {\n      const result: MeSHLookupResult = {\n        term,\n        found: false,\n        suggestions: startsWithResults.map((s) => s.label),\n      };\n      this.cache?.set('mesh', term, result);\n      return result;\n    }\n\n    // 2b. Try startsWith with progressively shorter input (handles suffix typos)\n    if (term.length > 3) {\n      for (let len = term.length - 1; len >= Math.max(term.length - 3, 3); len--) {\n        const truncated = term.slice(0, len);\n        const truncatedResults = await this.fetchLookup(truncated, 'startswith', 5);\n        if (truncatedResults.length > 0) {\n          const result: MeSHLookupResult = {\n            term,\n            found: false,\n            suggestions: truncatedResults.map((s) => s.label),\n          };\n          this.cache?.set('mesh', term, result);\n          return result;\n        }\n      }\n    }\n\n    // 2c. Multi-word progressive prefix: try word1 + word2.slice(0, N)\n    const words = term.split(/\\s+/);\n    if (words.length >= 2 && words[1]!.length > 3) {\n      const startN = Math.min(words[1]!.length - 4, words[1]!.length - 1);\n      const endN = 3;\n      let iterations = 0;\n      for (let n = startN; n >= endN && iterations < 3; n--, iterations++) {\n        const prefix = words[0]! + ' ' + words[1]!.slice(0, n);\n        const prefixResults = await this.fetchLookup(prefix, 'startswith', 5);\n        if (prefixResults.length > 0) {\n          const result: MeSHLookupResult = {\n            term,\n            found: false,\n            suggestions: prefixResults.map((s) => s.label),\n          };\n          this.cache?.set('mesh', term, result);\n          return result;\n        }\n      }\n    }\n\n    // 3. Try contains (full term) for typos and variant spellings\n    const containsResults = await this.fetchLookup(term, 'contains', 5);\n\n    if (containsResults.length > 0) {\n      const result: MeSHLookupResult = {\n        term,\n        found: false,\n        suggestions: containsResults.map((s) => s.label),\n      };\n      this.cache?.set('mesh', term, result);\n      return result;\n    }\n\n    // 4. Try startsWith with first word only (for multi-word terms)\n    //    Fetch up to 25 results and re-rank by Levenshtein distance\n    if (words.length > 1) {\n      const firstWord = words[0]!;\n      const firstWordResults = await this.fetchLookup(firstWord, 'startswith', 25);\n\n      if (firstWordResults.length > 0) {\n        const ranked = firstWordResults\n          .map((s) => ({\n            label: s.label,\n            distance: levenshteinDistance(term.toLowerCase(), s.label.toLowerCase()),\n          }))\n          .sort((a, b) => a.distance - b.distance)\n          .slice(0, 5)\n          .map((s) => s.label);\n        const result: MeSHLookupResult = { term, found: false, suggestions: ranked };\n        this.cache?.set('mesh', term, result);\n        return result;\n      }\n    }\n\n    const result: MeSHLookupResult = { term, found: false };\n    this.cache?.set('mesh', term, result);\n    return result;\n  }\n\n  /**\n   * Look up multiple MeSH terms.\n   */\n  async lookupTerms(terms: string[]): Promise<MeSHLookupResult[]> {\n    const results: MeSHLookupResult[] = [];\n    for (const term of terms) {\n      results.push(await this.lookupTerm(term));\n    }\n    return results;\n  }\n\n  private async fetchLookup(\n    label: string,\n    match: 'exact' | 'startswith' | 'contains',\n    limit: number\n  ): Promise<MeSHApiEntry[]> {\n    if (this.rateLimiter) {\n      await this.rateLimiter.acquire();\n    }\n\n    const params = new URLSearchParams({\n      label,\n      match,\n      limit: String(limit),\n    });\n\n    const url = `${MESH_LOOKUP_BASE_URL}?${params.toString()}`;\n\n    let response: Response;\n    try {\n      response = await fetch(url, {\n        signal: AbortSignal.timeout(this.timeoutMs),\n      });\n    } catch (error) {\n      const message =\n        error instanceof Error ? error.message : 'Unknown error';\n      throw new Error(`MeSH lookup failed: ${message}`);\n    }\n\n    if (!response.ok) {\n      throw new Error(\n        `MeSH lookup failed: HTTP ${response.status} ${response.statusText}`\n      );\n    }\n\n    return (await response.json()) as MeSHApiEntry[];\n  }\n}\n"],"names":["result"],"mappings":"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"}

package/dist/query/parser.js

@@ -12,7 +12,7 @@ async function parseQueryFile(filePath) {
 function detectShortKeywords(ast, threshold = 3) {
   const shortKeywords = /* @__PURE__ */ new Set();
   for (const block of ast.blocks) {
-    for (const keyword of block.terms.keywords) {
+    for (const keyword of block.terms.keywords ?? []) {
       if (keyword.length <= threshold) {
         shortKeywords.add(keyword);
       }

package/dist/query/parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser.js","sources":["../../src/query/parser.ts"],"sourcesContent":["/**\n * Query YAML Parser\n *\n * Parses YAML query files into validated QueryAST.\n * See spec/models/query-dsl.md for the full specification.\n */\n\nimport { readFile } from 'node:fs/promises';\nimport { parse } from 'yaml';\nimport type { QueryAST } from './types.js';\nimport { validateQueryFile } from './validator.js';\n\n/**\n * Parse a YAML string into a validated QueryAST.\n *\n * @param yaml - YAML string to parse\n * @returns Validated QueryAST\n * @throws Error if YAML is invalid or doesn't match schema\n */\nexport function parseQueryString(yaml: string): QueryAST {\n  const data = parse(yaml);\n  return validateQueryFile(data);\n}\n\n/**\n * Parse a YAML file into a validated QueryAST.\n *\n * @param filePath - Path to the YAML file\n * @returns Promise resolving to validated QueryAST\n * @throws Error if file doesn't exist, YAML is invalid, or doesn't match schema\n */\nexport async function parseQueryFile(filePath: string): Promise<QueryAST> {\n  const content = await readFile(filePath, 'utf-8');\n  return parseQueryString(content);\n}\n\n\n/**\n * Detect short keywords (potential acronyms) in a query.\n *\n * Short keywords (3 characters or fewer by default) may match unrelated\n * acronyms in different fields, producing noisy results.\n *\n * @param ast - Parsed QueryAST\n * @param threshold - Maximum length to consider \"short\" (default: 3)\n * @returns Array of unique short keywords found\n */\nexport function detectShortKeywords(ast: QueryAST, threshold = 3): string[] {\n  const shortKeywords = new Set<string>();\n\n  for (const block of ast.blocks) {\n    for (const keyword of block.terms.keywords) {\n      if (keyword.length <= threshold) {\n        shortKeywords.add(keyword);\n      }\n    }\n  }\n\n  return Array.from(shortKeywords);\n}\n"],"names":[],"mappings":";;;AAmBO,SAAS,iBAAiB,MAAwB;AACvD,QAAM,OAAO,MAAM,IAAI;AACvB,SAAO,kBAAkB,IAAI;AAC/B;AASA,eAAsB,eAAe,UAAqC;AACxE,QAAM,UAAU,MAAM,SAAS,UAAU,OAAO;AAChD,SAAO,iBAAiB,OAAO;AACjC;AAaO,SAAS,oBAAoB,KAAe,YAAY,GAAa;AAC1E,QAAM,oCAAoB,IAAA;AAE1B,aAAW,SAAS,IAAI,QAAQ;AAC9B,eAAW,WAAW,MAAM,MAAM,UAAU;AAC1C,UAAI,QAAQ,UAAU,WAAW;AAC/B,sBAAc,IAAI,OAAO;AAAA,MAC3B;AAAA,IACF;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,aAAa;AACjC;"}
+{"version":3,"file":"parser.js","sources":["../../src/query/parser.ts"],"sourcesContent":["/**\n * Query YAML Parser\n *\n * Parses YAML query files into validated QueryAST.\n * See spec/models/query-dsl.md for the full specification.\n */\n\nimport { readFile } from 'node:fs/promises';\nimport { parse } from 'yaml';\nimport type { QueryAST } from './types.js';\nimport { validateQueryFile } from './validator.js';\n\n/**\n * Parse a YAML string into a validated QueryAST.\n *\n * @param yaml - YAML string to parse\n * @returns Validated QueryAST\n * @throws Error if YAML is invalid or doesn't match schema\n */\nexport function parseQueryString(yaml: string): QueryAST {\n  const data = parse(yaml);\n  return validateQueryFile(data);\n}\n\n/**\n * Parse a YAML file into a validated QueryAST.\n *\n * @param filePath - Path to the YAML file\n * @returns Promise resolving to validated QueryAST\n * @throws Error if file doesn't exist, YAML is invalid, or doesn't match schema\n */\nexport async function parseQueryFile(filePath: string): Promise<QueryAST> {\n  const content = await readFile(filePath, 'utf-8');\n  return parseQueryString(content);\n}\n\n\n/**\n * Detect short keywords (potential acronyms) in a query.\n *\n * Short keywords (3 characters or fewer by default) may match unrelated\n * acronyms in different fields, producing noisy results.\n *\n * @param ast - Parsed QueryAST\n * @param threshold - Maximum length to consider \"short\" (default: 3)\n * @returns Array of unique short keywords found\n */\nexport function detectShortKeywords(ast: QueryAST, threshold = 3): string[] {\n  const shortKeywords = new Set<string>();\n\n  for (const block of ast.blocks) {\n    for (const keyword of block.terms.keywords ?? []) {\n      if (keyword.length <= threshold) {\n        shortKeywords.add(keyword);\n      }\n    }\n  }\n\n  return Array.from(shortKeywords);\n}\n"],"names":[],"mappings":";;;AAmBO,SAAS,iBAAiB,MAAwB;AACvD,QAAM,OAAO,MAAM,IAAI;AACvB,SAAO,kBAAkB,IAAI;AAC/B;AASA,eAAsB,eAAe,UAAqC;AACxE,QAAM,UAAU,MAAM,SAAS,UAAU,OAAO;AAChD,SAAO,iBAAiB,OAAO;AACjC;AAaO,SAAS,oBAAoB,KAAe,YAAY,GAAa;AAC1E,QAAM,oCAAoB,IAAA;AAE1B,aAAW,SAAS,IAAI,QAAQ;AAC9B,eAAW,WAAW,MAAM,MAAM,YAAY,CAAA,GAAI;AAChD,UAAI,QAAQ,UAAU,WAAW;AAC/B,sBAAc,IAAI,OAAO;AAAA,MAC3B;AAAA,IACF;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,aAAa;AACjC;"}

package/dist/query/types.d.ts

@@ -15,10 +15,10 @@ export type Operator = 'AND' | 'OR';
  */
 export interface TermBlock {
     /** Free-text keywords (supported by all databases) */
-    keywords: string[];
+    keywords?: string[] | undefined;
     /** MeSH terms (PubMed only) */
     mesh?: string[] | undefined;
-    /** Emtree terms (Embase only) */
+    /** Emtree terms (Embase/Scopus) */
     emtree?: string[] | undefined;
     /** ERIC Descriptors (ERIC only) */
     eric?: string[] | undefined;

package/dist/query/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/query/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,UAAU,GACV,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC9B,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,mBAAmB;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC/B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACtD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAClC,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,4CAA4C;IAC5C,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC;CACrE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/query/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,UAAU,GACV,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAChC,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC9B,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,mBAAmB;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC/B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACtD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAClC,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,4CAA4C;IAC5C,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC;CACrE"}

package/dist/query/validator.d.ts

@@ -15,7 +15,7 @@ export declare const fieldTypeSchema: z.ZodEnum<{
  * Schema for term block containing search terms.
  */
 export declare const termBlockSchema: z.ZodObject<{
-    keywords: z.ZodArray<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     mesh: z.ZodOptional<z.ZodArray<z.ZodString>>;
     emtree: z.ZodOptional<z.ZodArray<z.ZodString>>;
     eric: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -41,7 +41,7 @@ export declare const queryBlockSchema: z.ZodObject<{
         all: "all";
     }>;
     terms: z.ZodObject<{
-        keywords: z.ZodArray<z.ZodString>;
+        keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mesh: z.ZodOptional<z.ZodArray<z.ZodString>>;
         emtree: z.ZodOptional<z.ZodArray<z.ZodString>>;
         eric: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -156,7 +156,7 @@ export declare const queryFileSchema: z.ZodPipe<z.ZodObject<{
             all: "all";
         }>;
         terms: z.ZodObject<{
-            keywords: z.ZodArray<z.ZodString>;
+            keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
             mesh: z.ZodOptional<z.ZodArray<z.ZodString>>;
             emtree: z.ZodOptional<z.ZodArray<z.ZodString>>;
             eric: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -422,7 +422,7 @@ export declare const queryFileSchema: z.ZodPipe<z.ZodObject<{
     blocks: {
         field: "title" | "abstract" | "title_abstract" | "author" | "keyword" | "all";
         terms: {
-            keywords: string[];
+            keywords?: string[] | undefined;
             mesh?: string[] | undefined;
             emtree?: string[] | undefined;
             eric?: string[] | undefined;
@@ -524,7 +524,7 @@ export declare const queryFileSchema: z.ZodPipe<z.ZodObject<{
     query: {
         field: "title" | "abstract" | "title_abstract" | "author" | "keyword" | "all";
         terms: {
-            keywords: string[];
+            keywords?: string[] | undefined;
             mesh?: string[] | undefined;
             emtree?: string[] | undefined;
             eric?: string[] | undefined;

package/dist/query/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/query/validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;EAO1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;iBAM1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc;;;EAAwB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;iBAI3B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;GAcrB,CAAC;AAEN;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwB3B,CAAC;AAEN;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;EAO7B,CAAC;AAiBH;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAcvB,CAAC;AAEN;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAEzD;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,EAAE,CAWvE"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/query/validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;EAO1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;iBAS3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc;;;EAAwB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;iBAI3B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;GAcrB,CAAC;AAEN;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwB3B,CAAC;AAEN;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;EAO7B,CAAC;AAiBH;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAcvB,CAAC;AAEN;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAEzD;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,EAAE,CAWvE"}

package/dist/query/validator.js

@@ -8,12 +8,15 @@ const fieldTypeSchema = z.enum([
   "all"
 ]);
 const termBlockSchema = z.object({
-  keywords: z.array(z.string()).min(1),
+  keywords: z.array(z.string()).min(1).optional(),
   mesh: z.array(z.string()).optional(),
   emtree: z.array(z.string()).optional(),
   eric: z.array(z.string()).optional(),
   exclude: z.array(z.string()).optional()
-});
+}).refine(
+  (data) => data.keywords?.length || data.mesh?.length || data.emtree?.length || data.eric?.length,
+  { message: "At least one of keywords, mesh, emtree, or eric is required" }
+);
 const operatorSchema = z.enum(["AND", "OR"]);
 const queryBlockSchema = z.object({
   field: fieldTypeSchema,

package/dist/query/validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"validator.js","sources":["../../src/query/validator.ts"],"sourcesContent":["/**\n * Query Schema Validation using Zod\n *\n * Validates query YAML structure against the query DSL schema.\n * See spec/models/query-dsl.md for the full specification.\n */\n\nimport { z } from 'zod';\nimport type { QueryAST } from './types.js';\n\n/**\n * Schema for field types.\n */\nexport const fieldTypeSchema = z.enum([\n  'title',\n  'abstract',\n  'title_abstract',\n  'author',\n  'keyword',\n  'all',\n]);\n\n/**\n * Schema for term block containing search terms.\n */\nexport const termBlockSchema = z.object({\n  keywords: z.array(z.string()).min(1),\n  mesh: z.array(z.string()).optional(),\n  emtree: z.array(z.string()).optional(),\n  eric: z.array(z.string()).optional(),\n  exclude: z.array(z.string()).optional(),\n});\n\n/**\n * Schema for operator.\n */\nexport const operatorSchema = z.enum(['AND', 'OR']);\n\n/**\n * Schema for query block.\n */\nexport const queryBlockSchema = z.object({\n  field: fieldTypeSchema,\n  terms: termBlockSchema,\n  operator: operatorSchema,\n});\n\n/**\n * Schema for publication type filter.\n */\nexport const publicationTypeFilterSchema = z.object({\n  include: z.array(z.string()).optional(),\n  exclude: z.array(z.string()).optional(),\n});\n\n/**\n * Schema for filters (YAML input format with snake_case).\n * Transforms to camelCase for internal use.\n */\nexport const filtersSchema = z\n  .object({\n    year_from: z.number().int().optional(),\n    year_to: z.number().int().optional(),\n    language: z.array(z.string()).optional(),\n    publication_types: publicationTypeFilterSchema.optional(),\n  })\n  .optional()\n  .default({})\n  .transform((data) => ({\n    yearFrom: data.year_from,\n    yearTo: data.year_to,\n    languages: data.language,\n    publicationTypes: data.publication_types,\n  }));\n\n/**\n * Schema for override block (YAML input format).\n */\nexport const overrideBlockSchema = z\n  .object({\n    filters: z\n      .object({\n        year_from: z.number().int().optional(),\n        year_to: z.number().int().optional(),\n        language: z.array(z.string()).optional(),\n        publication_types: publicationTypeFilterSchema.optional(),\n      })\n      .optional(),\n    categories: z.array(z.string()).optional(),\n    source_types: z.array(z.string()).optional(),\n  })\n  .transform((data) => ({\n    filters: data.filters\n      ? {\n          yearFrom: data.filters.year_from,\n          yearTo: data.filters.year_to,\n          languages: data.filters.language,\n          publicationTypes: data.filters.publication_types,\n        }\n      : undefined,\n    categories: data.categories,\n    sourceTypes: data.source_types,\n  }));\n\n/**\n * Provider names schema.\n */\nexport const providerNameSchema = z.enum([\n  'pubmed',\n  'scopus',\n  'eric',\n  'arxiv',\n  'wos',\n  'embase',\n]);\n\n/**\n * Schema for overrides object (partial record of provider -> override).\n */\nconst overridesSchema = z\n  .object({\n    pubmed: overrideBlockSchema.optional(),\n    scopus: overrideBlockSchema.optional(),\n    eric: overrideBlockSchema.optional(),\n    arxiv: overrideBlockSchema.optional(),\n    wos: overrideBlockSchema.optional(),\n    embase: overrideBlockSchema.optional(),\n  })\n  .optional()\n  .default({});\n\n/**\n * Schema for the complete query file (YAML input format).\n * Transforms to QueryAST for internal use.\n */\nexport const queryFileSchema = z\n  .object({\n    name: z.string().min(1),\n    description: z.string().optional(),\n    query: z.array(queryBlockSchema).min(1),\n    filters: filtersSchema,\n    overrides: overridesSchema,\n  })\n  .transform((data) => ({\n    name: data.name,\n    description: data.description,\n    blocks: data.query,\n    filters: data.filters,\n    overrides: data.overrides,\n  }));\n\n/**\n * Validate a parsed YAML object against the query schema.\n * Returns a validated QueryAST.\n */\nexport function validateQueryFile(data: unknown): QueryAST {\n  return queryFileSchema.parse(data);\n}\n\n/**\n * Validation error with path information.\n */\nexport class ValidationError extends Error {\n  constructor(\n    public readonly path: string,\n    message: string\n  ) {\n    super(message);\n    this.name = 'ValidationError';\n  }\n}\n\n/**\n * Format Zod validation errors into an array of ValidationError objects.\n *\n * @param data - The data to validate\n * @returns Array of ValidationError objects (empty if valid)\n */\nexport function formatValidationErrors(data: unknown): ValidationError[] {\n  const result = queryFileSchema.safeParse(data);\n\n  if (result.success) {\n    return [];\n  }\n\n  return result.error.issues.map((issue) => {\n    const path = issue.path.join('.');\n    return new ValidationError(path, issue.message);\n  });\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"validator.js","sources":["../../src/query/validator.ts"],"sourcesContent":["/**\n * Query Schema Validation using Zod\n *\n * Validates query YAML structure against the query DSL schema.\n * See spec/models/query-dsl.md for the full specification.\n */\n\nimport { z } from 'zod';\nimport type { QueryAST } from './types.js';\n\n/**\n * Schema for field types.\n */\nexport const fieldTypeSchema = z.enum([\n  'title',\n  'abstract',\n  'title_abstract',\n  'author',\n  'keyword',\n  'all',\n]);\n\n/**\n * Schema for term block containing search terms.\n */\nexport const termBlockSchema = z.object({\n  keywords: z.array(z.string()).min(1).optional(),\n  mesh: z.array(z.string()).optional(),\n  emtree: z.array(z.string()).optional(),\n  eric: z.array(z.string()).optional(),\n  exclude: z.array(z.string()).optional(),\n}).refine(\n  (data) => data.keywords?.length || data.mesh?.length || data.emtree?.length || data.eric?.length,\n  { message: 'At least one of keywords, mesh, emtree, or eric is required' }\n);\n\n/**\n * Schema for operator.\n */\nexport const operatorSchema = z.enum(['AND', 'OR']);\n\n/**\n * Schema for query block.\n */\nexport const queryBlockSchema = z.object({\n  field: fieldTypeSchema,\n  terms: termBlockSchema,\n  operator: operatorSchema,\n});\n\n/**\n * Schema for publication type filter.\n */\nexport const publicationTypeFilterSchema = z.object({\n  include: z.array(z.string()).optional(),\n  exclude: z.array(z.string()).optional(),\n});\n\n/**\n * Schema for filters (YAML input format with snake_case).\n * Transforms to camelCase for internal use.\n */\nexport const filtersSchema = z\n  .object({\n    year_from: z.number().int().optional(),\n    year_to: z.number().int().optional(),\n    language: z.array(z.string()).optional(),\n    publication_types: publicationTypeFilterSchema.optional(),\n  })\n  .optional()\n  .default({})\n  .transform((data) => ({\n    yearFrom: data.year_from,\n    yearTo: data.year_to,\n    languages: data.language,\n    publicationTypes: data.publication_types,\n  }));\n\n/**\n * Schema for override block (YAML input format).\n */\nexport const overrideBlockSchema = z\n  .object({\n    filters: z\n      .object({\n        year_from: z.number().int().optional(),\n        year_to: z.number().int().optional(),\n        language: z.array(z.string()).optional(),\n        publication_types: publicationTypeFilterSchema.optional(),\n      })\n      .optional(),\n    categories: z.array(z.string()).optional(),\n    source_types: z.array(z.string()).optional(),\n  })\n  .transform((data) => ({\n    filters: data.filters\n      ? {\n          yearFrom: data.filters.year_from,\n          yearTo: data.filters.year_to,\n          languages: data.filters.language,\n          publicationTypes: data.filters.publication_types,\n        }\n      : undefined,\n    categories: data.categories,\n    sourceTypes: data.source_types,\n  }));\n\n/**\n * Provider names schema.\n */\nexport const providerNameSchema = z.enum([\n  'pubmed',\n  'scopus',\n  'eric',\n  'arxiv',\n  'wos',\n  'embase',\n]);\n\n/**\n * Schema for overrides object (partial record of provider -> override).\n */\nconst overridesSchema = z\n  .object({\n    pubmed: overrideBlockSchema.optional(),\n    scopus: overrideBlockSchema.optional(),\n    eric: overrideBlockSchema.optional(),\n    arxiv: overrideBlockSchema.optional(),\n    wos: overrideBlockSchema.optional(),\n    embase: overrideBlockSchema.optional(),\n  })\n  .optional()\n  .default({});\n\n/**\n * Schema for the complete query file (YAML input format).\n * Transforms to QueryAST for internal use.\n */\nexport const queryFileSchema = z\n  .object({\n    name: z.string().min(1),\n    description: z.string().optional(),\n    query: z.array(queryBlockSchema).min(1),\n    filters: filtersSchema,\n    overrides: overridesSchema,\n  })\n  .transform((data) => ({\n    name: data.name,\n    description: data.description,\n    blocks: data.query,\n    filters: data.filters,\n    overrides: data.overrides,\n  }));\n\n/**\n * Validate a parsed YAML object against the query schema.\n * Returns a validated QueryAST.\n */\nexport function validateQueryFile(data: unknown): QueryAST {\n  return queryFileSchema.parse(data);\n}\n\n/**\n * Validation error with path information.\n */\nexport class ValidationError extends Error {\n  constructor(\n    public readonly path: string,\n    message: string\n  ) {\n    super(message);\n    this.name = 'ValidationError';\n  }\n}\n\n/**\n * Format Zod validation errors into an array of ValidationError objects.\n *\n * @param data - The data to validate\n * @returns Array of ValidationError objects (empty if valid)\n */\nexport function formatValidationErrors(data: unknown): ValidationError[] {\n  const result = queryFileSchema.safeParse(data);\n\n  if (result.success) {\n    return [];\n  }\n\n  return result.error.issues.map((issue) => {\n    const path = issue.path.join('.');\n    return new ValidationError(path, issue.message);\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/query/vocab-cache.d.ts

@@ -0,0 +1,15 @@
+import { MeSHLookupResult } from './mesh-lookup.js';
+export declare class VocabCache {
+    private store;
+    private readonly cachePath;
+    private readonly ttlMs;
+    constructor(options?: {
+        cachePath?: string;
+        ttlMs?: number;
+    });
+    load(): Promise<void>;
+    save(): Promise<void>;
+    get(vocabulary: string, term: string): MeSHLookupResult | undefined;
+    set(vocabulary: string, term: string, result: MeSHLookupResult): void;
+}
+//# sourceMappingURL=vocab-cache.d.ts.map

package/dist/query/vocab-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocab-cache.d.ts","sourceRoot":"","sources":["../../src/query/vocab-cache.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAWzD,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAOtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAanE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI;CAItE"}

package/dist/query/vocab-cache.js

@@ -0,0 +1,44 @@
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { getConfigDir } from "../config/paths.js";
+const DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
+class VocabCache {
+  store = {};
+  cachePath;
+  ttlMs;
+  constructor(options) {
+    this.cachePath = options?.cachePath ?? join(getConfigDir(), "cache", "vocab-lookup.json");
+    this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+  }
+  async load() {
+    try {
+      const raw = await readFile(this.cachePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      this.store = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      this.store = {};
+    }
+  }
+  async save() {
+    await mkdir(dirname(this.cachePath), { recursive: true });
+    await writeFile(this.cachePath, JSON.stringify(this.store), "utf-8");
+  }
+  get(vocabulary, term) {
+    const key = `${vocabulary}:${term}`;
+    const entry = this.store[key];
+    if (!entry) return void 0;
+    if (Date.now() - entry.cachedAt > this.ttlMs) {
+      delete this.store[key];
+      return void 0;
+    }
+    return entry.result;
+  }
+  set(vocabulary, term, result) {
+    const key = `${vocabulary}:${term}`;
+    this.store[key] = { result, cachedAt: Date.now() };
+  }
+}
+export {
+  VocabCache
+};
+//# sourceMappingURL=vocab-cache.js.map

package/dist/query/vocab-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocab-cache.js","sources":["../../src/query/vocab-cache.ts"],"sourcesContent":["/**\n * File-based cache for vocabulary lookup results.\n *\n * Stores MeSH (and future vocabulary) lookup results on disk to avoid\n * redundant API calls. TTL defaults to 30 days.\n */\nimport { readFile, writeFile, mkdir } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { getConfigDir } from '../config/paths.js';\nimport type { MeSHLookupResult } from './mesh-lookup.js';\n\nconst DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days\n\ninterface VocabCacheEntry {\n  result: MeSHLookupResult;\n  cachedAt: number; // Unix ms\n}\n\ntype VocabCacheStore = Record<string, VocabCacheEntry>;\n\nexport class VocabCache {\n  private store: VocabCacheStore = {};\n  private readonly cachePath: string;\n  private readonly ttlMs: number;\n\n  constructor(options?: { cachePath?: string; ttlMs?: number }) {\n    this.cachePath =\n      options?.cachePath ??\n      join(getConfigDir(), 'cache', 'vocab-lookup.json');\n    this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;\n  }\n\n  async load(): Promise<void> {\n    try {\n      const raw = await readFile(this.cachePath, 'utf-8');\n      const parsed: unknown = JSON.parse(raw);\n      this.store =\n        typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)\n          ? (parsed as VocabCacheStore)\n          : {};\n    } catch {\n      // File missing or corrupted JSON — start with empty cache\n      this.store = {};\n    }\n  }\n\n  async save(): Promise<void> {\n    await mkdir(dirname(this.cachePath), { recursive: true });\n    await writeFile(this.cachePath, JSON.stringify(this.store), 'utf-8');\n  }\n\n  get(vocabulary: string, term: string): MeSHLookupResult | undefined {\n    const key = `${vocabulary}:${term}`;\n    const entry = this.store[key];\n    if (!entry) return undefined;\n\n    if (Date.now() - entry.cachedAt > this.ttlMs) {\n      delete this.store[key];\n      return undefined;\n    }\n\n    return entry.result;\n  }\n\n  set(vocabulary: string, term: string, result: MeSHLookupResult): void {\n    const key = `${vocabulary}:${term}`;\n    this.store[key] = { result, cachedAt: Date.now() };\n  }\n}\n"],"names":[],"mappings":";;;AAWA,MAAM,iBAAiB,KAAK,KAAK,KAAK,KAAK;AASpC,MAAM,WAAW;AAAA,EACd,QAAyB,CAAA;AAAA,EAChB;AAAA,EACA;AAAA,EAEjB,YAAY,SAAkD;AAC5D,SAAK,YACH,SAAS,aACT,KAAK,aAAA,GAAgB,SAAS,mBAAmB;AACnD,SAAK,QAAQ,SAAS,SAAS;AAAA,EACjC;AAAA,EAEA,MAAM,OAAsB;AAC1B,QAAI;AACF,YAAM,MAAM,MAAM,SAAS,KAAK,WAAW,OAAO;AAClD,YAAM,SAAkB,KAAK,MAAM,GAAG;AACtC,WAAK,QACH,OAAO,WAAW,YAAY,WAAW,QAAQ,CAAC,MAAM,QAAQ,MAAM,IACjE,SACD,CAAA;AAAA,IACR,QAAQ;AAEN,WAAK,QAAQ,CAAA;AAAA,IACf;AAAA,EACF;AAAA,EAEA,MAAM,OAAsB;AAC1B,UAAM,MAAM,QAAQ,KAAK,SAAS,GAAG,EAAE,WAAW,MAAM;AACxD,UAAM,UAAU,KAAK,WAAW,KAAK,UAAU,KAAK,KAAK,GAAG,OAAO;AAAA,EACrE;AAAA,EAEA,IAAI,YAAoB,MAA4C;AAClE,UAAM,MAAM,GAAG,UAAU,IAAI,IAAI;AACjC,UAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,QAAI,CAAC,MAAO,QAAO;AAEnB,QAAI,KAAK,IAAA,IAAQ,MAAM,WAAW,KAAK,OAAO;AAC5C,aAAO,KAAK,MAAM,GAAG;AACrB,aAAO;AAAA,IACT;AAEA,WAAO,MAAM;AAAA,EACf;AAAA,EAEA,IAAI,YAAoB,MAAc,QAAgC;AACpE,UAAM,MAAM,GAAG,UAAU,IAAI,IAAI;AACjC,SAAK,MAAM,GAAG,IAAI,EAAE,QAAQ,UAAU,KAAK,MAAI;AAAA,EACjD;AACF;"}

package/dist/query/vocab-validator.d.ts

@@ -0,0 +1,71 @@
+import { QueryAST } from './types.js';
+import { MeSHLookupClient } from './mesh-lookup.js';
+import { Provider } from '../providers/base/types.js';
+import { VocabCache } from './vocab-cache.js';
+/** Supported controlled vocabulary types. */
+export type VocabType = 'mesh' | 'eric' | 'emtree';
+/**
+ * A controlled vocabulary term extracted from a QueryAST.
+ */
+export interface VocabTerm {
+    term: string;
+    vocabulary: VocabType;
+}
+/**
+ * Result of validating a single controlled vocabulary term.
+ */
+export interface VocabTermResult {
+    term: string;
+    vocabulary: VocabType;
+    found: boolean;
+    suggestions?: string[];
+}
+/**
+ * A controlled vocabulary term that failed due to an API error.
+ */
+export interface VocabTermError {
+    term: string;
+    vocabulary: VocabType;
+    error: string;
+}
+/**
+ * Result of validating all controlled vocabulary terms in a query.
+ */
+export interface VocabValidationResult {
+    valid: VocabTermResult[];
+    invalid: VocabTermResult[];
+    errors: VocabTermError[];
+}
+/**
+ * Extract all controlled vocabulary terms from a QueryAST.
+ * Terms are deduplicated across blocks.
+ */
+export declare function extractControlledVocabTerms(ast: QueryAST): VocabTerm[];
+/**
+ * A count-based vocabulary validator.
+ * Validates terms by executing a count-only search — hit count 0 means invalid.
+ */
+export interface CountVocabValidator {
+    vocabulary: VocabType;
+    countTerm: (term: string) => Promise<number>;
+}
+/**
+ * Validate all controlled vocabulary terms in a QueryAST.
+ *
+ * MeSH terms are validated via the MeSH lookup API (exact match + suggestions).
+ * ERIC/Emtree terms are validated via count-only search when countValidators are provided.
+ * Terms whose vocabulary has no validator are skipped silently.
+ *
+ * Different vocabulary groups are validated in parallel; within each group,
+ * concurrency is limited to 3 requests at a time.
+ */
+export declare function validateControlledVocab(ast: QueryAST, meshClient: MeSHLookupClient, options?: {
+    countValidators?: CountVocabValidator[];
+}): Promise<VocabValidationResult>;
+export declare function createEricCountValidator(provider: Provider, options?: {
+    cache?: VocabCache;
+}): CountVocabValidator;
+export declare function createEmtreeCountValidator(provider: Provider, options?: {
+    cache?: VocabCache;
+}): CountVocabValidator;
+//# sourceMappingURL=vocab-validator.d.ts.map

package/dist/query/vocab-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocab-validator.d.ts","sourceRoot":"","sources":["../../src/query/vocab-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAiC,MAAM,4BAA4B,CAAC;AAC1F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,QAAQ,GAAG,SAAS,EAAE,CA0BtE;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9C;AAsBD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,QAAQ,EACb,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAA;CAAE,GACpD,OAAO,CAAC,qBAAqB,CAAC,CA2FhC;AAgDD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,GAC/B,mBAAmB,CAErB;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,GAC/B,mBAAmB,CAErB"}