wiki-graph-core 0.3.1

package/dist/wikimatch/wikispine.js

@@ -0,0 +1,399 @@
+import { spawn } from "child_process";
+const WIKISPINE_RUNTIME_GUIDE_URL = "https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md";
+const DEFAULT_WIKISPINE_FETCH_ENDPOINT = "https://wikispi-service-cxbfjlteab.cn-hangzhou.fcapp.run";
+async function matchWikispineSentenceCandidates(options) {
+  const candidates = [];
+  let candidateIndex = 1;
+  for (const sentence of options.sentences) {
+    for (const matched of await matchSentence(sentence, options)) {
+      const surface = sentence.text.slice(matched.start, matched.end);
+      candidates.push({
+        id: `c${candidateIndex}`,
+        qidOptions: matched.qids.map(toQidOption),
+        range: {
+          end: sentence.range.start + matched.end,
+          start: sentence.range.start + matched.start
+        },
+        surface
+      });
+      candidateIndex += 1;
+    }
+    await options.onProgress?.({ coveredRangeEnd: sentence.range.end });
+  }
+  return candidates;
+}
+async function matchSentence(sentence, options) {
+  return resolveProvider(options) === "fetch" ? await fetchWikispineMatch(options, sentence) : await runWikispineMatch(
+    options.command ?? "wikispine",
+    buildMatchArgs(options),
+    sentence,
+    options
+  );
+}
+async function testWikispineRuntime(options) {
+  const provider = resolveProvider(options);
+  const startedAt = Date.now();
+  if (provider === "fetch") {
+    const endpoint = requireEndpoint(options.endpoint);
+    const metadata = await fetchWikispineMetadata(endpoint, options.fetch);
+    await fetchWikispineMatch(
+      {
+        ...options,
+        endpoint,
+        maxCandidatesPerSurface: 1
+      },
+      {
+        id: "test",
+        range: { end: 7, start: 0 },
+        text: "\u5317\u4EAC\u5927\u5B66\u4F4D\u4E8E\u5317\u4EAC\u3002"
+      }
+    );
+    return {
+      durationMs: Date.now() - startedAt,
+      metadata,
+      ok: true,
+      provider
+    };
+  }
+  await runWikispineMatch(
+    options.command ?? "wikispine",
+    buildMatchArgs({
+      ...options,
+      maxCandidatesPerSurface: 1
+    }),
+    {
+      id: "test",
+      range: { end: 7, start: 0 },
+      text: "\u5317\u4EAC\u5927\u5B66\u4F4D\u4E8E\u5317\u4EAC\u3002"
+    },
+    {}
+  );
+  return {
+    durationMs: Date.now() - startedAt,
+    ok: true,
+    provider
+  };
+}
+async function runWikispineMatch(command, args, sentence, options) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const progress = createWikispineProgressReporter(options.onProgress, {
+      onFailure: (error) => {
+        reject(error);
+        child.kill();
+      }
+    });
+    const parser = createWikispineNdjsonParser({
+      onMatch: (match) => {
+        progress.report({
+          coveredRangeEnd: sentence.range.start + match.end
+        });
+      }
+    });
+    const stderr = [];
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      try {
+        parser.push(chunk);
+      } catch (error) {
+        reject(toError(error));
+        child.kill();
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr.push(chunk);
+    });
+    child.on("error", (error) => {
+      reject(
+        new Error(
+          formatWikispineRuntimeError(
+            `Failed to start wikispine command: ${error.message}`
+          )
+        )
+      );
+    });
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(
+          new Error(
+            formatWikispineRuntimeError(
+              `wikispine match failed with exit code ${code}: ${Buffer.concat(stderr).toString("utf8")}`
+            )
+          )
+        );
+        return;
+      }
+      void (async () => {
+        try {
+          const matches = parser.finish();
+          await progress.wait();
+          resolve(matches);
+        } catch (error) {
+          reject(toError(error));
+        }
+      })();
+    });
+    child.stdin.end(sentence.text);
+  });
+}
+function buildMatchArgs(options) {
+  const args = ["match"];
+  if (options.dataDir !== void 0) {
+    args.push("--data-dir", options.dataDir);
+  }
+  if (options.includeDisambiguation === false) {
+    args.push("--exclude-disambiguation");
+  }
+  if (options.maxCandidatesPerSurface !== void 0) {
+    args.push(
+      "--max-candidates-per-surface",
+      String(options.maxCandidatesPerSurface)
+    );
+  }
+  return args;
+}
+async function fetchWikispineMatch(options, sentence) {
+  const endpoint = requireEndpoint(options.endpoint);
+  const response = await (options.fetch ?? fetch)(`${endpoint}/match`, {
+    body: JSON.stringify({
+      options: {
+        ...options.includeDisambiguation === void 0 ? {} : { include_disambiguation: options.includeDisambiguation },
+        ...options.maxCandidatesPerSurface === void 0 ? {} : {
+          max_candidates_per_surface: options.maxCandidatesPerSurface
+        }
+      },
+      text: sentence.text
+    }),
+    headers: {
+      accept: "application/x-ndjson",
+      "content-type": "application/json"
+    },
+    method: "POST"
+  });
+  if (!response.ok) {
+    throw new Error(
+      formatWikispineRuntimeError(
+        `WikiSpine fetch provider failed with HTTP ${response.status}: ${await response.text()}`
+      )
+    );
+  }
+  const progress = createWikispineProgressReporter(options.onProgress);
+  const parser = createWikispineNdjsonParser({
+    onMatch: (match) => {
+      progress.report({
+        coveredRangeEnd: sentence.range.start + match.end
+      });
+    }
+  });
+  if (response.body === null) {
+    parser.push(await response.text());
+    const matches2 = parser.finish();
+    await progress.wait();
+    return matches2;
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    parser.push(decoder.decode(value, { stream: true }));
+    progress.throwIfFailed();
+  }
+  parser.push(decoder.decode());
+  const matches = parser.finish();
+  await progress.wait();
+  return matches;
+}
+function createWikispineProgressReporter(onProgress, options) {
+  const tasks = [];
+  let failure;
+  function fail(error) {
+    if (failure !== void 0) {
+      return;
+    }
+    failure = toError(error);
+    options?.onFailure?.(failure);
+  }
+  return {
+    report: (progress) => {
+      if (onProgress === void 0 || failure !== void 0) {
+        return;
+      }
+      try {
+        tasks.push(Promise.resolve(onProgress(progress)).catch(fail));
+      } catch (error) {
+        fail(error);
+      }
+    },
+    throwIfFailed: () => {
+      if (failure !== void 0) {
+        throw failure;
+      }
+    },
+    wait: async () => {
+      await Promise.all(tasks);
+      if (failure !== void 0) {
+        throw failure;
+      }
+    }
+  };
+}
+async function fetchWikispineMetadata(endpoint, fetchFn = fetch) {
+  const ready = await fetchFn(`${endpoint}/readyz`);
+  if (!ready.ok) {
+    throw new Error(
+      formatWikispineRuntimeError(
+        `WikiSpine fetch provider is not ready: HTTP ${ready.status}.`
+      )
+    );
+  }
+  const response = await fetchFn(`${endpoint}/metadata`);
+  if (!response.ok) {
+    throw new Error(
+      formatWikispineRuntimeError(
+        `WikiSpine metadata request failed with HTTP ${response.status}.`
+      )
+    );
+  }
+  try {
+    return parseWikispineMetadata(await response.json());
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("setup guide")) {
+      throw error;
+    }
+    throw new Error(
+      formatWikispineRuntimeError(
+        `Invalid WikiSpine metadata response: ${error instanceof Error ? error.message : String(error)}`
+      )
+    );
+  }
+}
+function createWikispineNdjsonParser(input) {
+  const matches = [];
+  let buffer = "";
+  function parseLine(line) {
+    if (line.trim() === "") {
+      return;
+    }
+    const event = parseWikispineEvent(JSON.parse(line));
+    if (event.type === "match") {
+      matches.push(event.match);
+      input?.onMatch?.(event.match);
+    }
+  }
+  function wrapParseError(error) {
+    return new Error(
+      formatWikispineRuntimeError(
+        `Invalid WikiSpine match response: ${error instanceof Error ? error.message : String(error)}`
+      )
+    );
+  }
+  return {
+    finish: () => {
+      try {
+        parseLine(buffer);
+        buffer = "";
+        return matches;
+      } catch (error) {
+        throw wrapParseError(error);
+      }
+    },
+    push: (chunk) => {
+      try {
+        buffer += chunk;
+        const lines = buffer.split(/\r?\n/u);
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          parseLine(line);
+        }
+      } catch (error) {
+        throw wrapParseError(error);
+      }
+    }
+  };
+}
+function parseWikispineEvent(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error("Expected wikispine event to be an object.");
+  }
+  const record = value;
+  if (record.type === "done") {
+    return { type: "done" };
+  }
+  if (record.type === "match" && isWikispineMatchRecord(record.match)) {
+    return {
+      match: record.match,
+      type: "match"
+    };
+  }
+  throw new Error(`Unexpected wikispine event: ${JSON.stringify(value)}`);
+}
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function parseWikispineMetadata(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error(
+      formatWikispineRuntimeError("Expected WikiSpine metadata.")
+    );
+  }
+  const record = value;
+  if (typeof record.automaton_shard_count !== "number" || typeof record.format !== "string" || typeof record.qid_count !== "number" || typeof record.surface_count !== "number" || typeof record.surface_normalization !== "string") {
+    throw new Error(formatWikispineRuntimeError("Invalid WikiSpine metadata."));
+  }
+  return {
+    automaton_shard_count: record.automaton_shard_count,
+    format: record.format,
+    qid_count: record.qid_count,
+    surface_count: record.surface_count,
+    surface_normalization: record.surface_normalization
+  };
+}
+function isWikispineMatchRecord(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value;
+  return typeof record.end === "number" && Array.isArray(record.qids) && record.qids.every(isWikispineQidCandidate) && typeof record.start === "number" && typeof record.surface_id === "number";
+}
+function isWikispineQidCandidate(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value;
+  return (!("disambiguation" in record) || typeof record.disambiguation === "boolean") && typeof record.qid === "string" && /^Q[1-9]\d*$/u.test(record.qid);
+}
+function toQidOption(candidate) {
+  return {
+    isDisambiguation: candidate.disambiguation === true,
+    qid: candidate.qid
+  };
+}
+function resolveProvider(options) {
+  return options.provider ?? "cli";
+}
+function requireEndpoint(endpoint) {
+  const normalized = (endpoint ?? DEFAULT_WIKISPINE_FETCH_ENDPOINT).trim().replace(/\/+$/u, "");
+  if (normalized === "") {
+    throw new Error(
+      formatWikispineRuntimeError(
+        "WikiSpine fetch provider has no default endpoint."
+      )
+    );
+  }
+  return normalized;
+}
+function formatWikispineRuntimeError(message) {
+  return `${message}
+WikiSpine setup guide: ${WIKISPINE_RUNTIME_GUIDE_URL}`;
+}
+export {
+  DEFAULT_WIKISPINE_FETCH_ENDPOINT,
+  matchWikispineSentenceCandidates,
+  testWikispineRuntime
+};
+//# sourceMappingURL=wikispine.js.map

package/dist/wikimatch/wikispine.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikimatch/wikispine.ts"],"sourcesContent":["import { spawn } from \"child_process\";\n\nimport type {\n  WikimatchCandidate,\n  WikimatchQidOption,\n  WikimatchSentence,\n} from \"./types.js\";\n\nexport interface MatchWikispineSentenceCandidatesOptions {\n  readonly command?: string;\n  readonly dataDir?: string;\n  readonly endpoint?: string;\n  readonly fetch?: typeof fetch;\n  readonly includeDisambiguation?: boolean;\n  readonly maxCandidatesPerSurface?: number;\n  readonly onProgress?: (\n    progress: WikispineMatchProgress,\n  ) => Promise<void> | void;\n  readonly provider?: WikispineProvider;\n  readonly sentences: readonly WikimatchSentence[];\n}\n\nexport type WikispineProvider = \"cli\" | \"fetch\";\n\nexport interface WikispineMatchProgress {\n  readonly coveredRangeEnd: number;\n}\n\nexport interface TestWikispineRuntimeOptions {\n  readonly command?: string;\n  readonly dataDir?: string;\n  readonly endpoint?: string;\n  readonly fetch?: typeof fetch;\n  readonly provider?: WikispineProvider;\n}\n\nexport interface WikispineRuntimeTestResult {\n  readonly durationMs: number;\n  readonly metadata?: WikispineMetadata;\n  readonly ok: true;\n  readonly provider: WikispineProvider;\n}\n\ninterface WikispineMatchEvent {\n  readonly match: WikispineMatchRecord;\n  readonly type: \"match\";\n}\n\ninterface WikispineDoneEvent {\n  readonly stats?: unknown;\n  readonly type: \"done\";\n}\n\ntype WikispineEvent = WikispineDoneEvent | WikispineMatchEvent;\n\ninterface WikispineMatchRecord {\n  readonly end: number;\n  readonly qids: readonly WikispineQidCandidate[];\n  readonly start: number;\n  readonly surface_id: number;\n}\n\ninterface WikispineQidCandidate {\n  readonly disambiguation?: boolean;\n  readonly qid: string;\n}\n\ninterface WikispineMetadata {\n  readonly automaton_shard_count: number;\n  readonly format: string;\n  readonly qid_count: number;\n  readonly surface_count: number;\n  readonly surface_normalization: string;\n}\n\nconst WIKISPINE_RUNTIME_GUIDE_URL =\n  \"https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md\";\nexport const DEFAULT_WIKISPINE_FETCH_ENDPOINT =\n  \"https://wikispi-service-cxbfjlteab.cn-hangzhou.fcapp.run\";\n\nexport async function matchWikispineSentenceCandidates(\n  options: MatchWikispineSentenceCandidatesOptions,\n): Promise<readonly WikimatchCandidate[]> {\n  const candidates: WikimatchCandidate[] = [];\n  let candidateIndex = 1;\n\n  for (const sentence of options.sentences) {\n    for (const matched of await matchSentence(sentence, options)) {\n      const surface = sentence.text.slice(matched.start, matched.end);\n\n      candidates.push({\n        id: `c${candidateIndex}`,\n        qidOptions: matched.qids.map(toQidOption),\n        range: {\n          end: sentence.range.start + matched.end,\n          start: sentence.range.start + matched.start,\n        },\n        surface,\n      });\n      candidateIndex += 1;\n    }\n    await options.onProgress?.({ coveredRangeEnd: sentence.range.end });\n  }\n\n  return candidates;\n}\n\nasync function matchSentence(\n  sentence: WikimatchSentence,\n  options: MatchWikispineSentenceCandidatesOptions,\n): Promise<readonly WikispineMatchRecord[]> {\n  return resolveProvider(options) === \"fetch\"\n    ? await fetchWikispineMatch(options, sentence)\n    : await runWikispineMatch(\n        options.command ?? \"wikispine\",\n        buildMatchArgs(options),\n        sentence,\n        options,\n      );\n}\n\nexport async function testWikispineRuntime(\n  options: TestWikispineRuntimeOptions,\n): Promise<WikispineRuntimeTestResult> {\n  const provider = resolveProvider(options);\n  const startedAt = Date.now();\n\n  if (provider === \"fetch\") {\n    const endpoint = requireEndpoint(options.endpoint);\n    const metadata = await fetchWikispineMetadata(endpoint, options.fetch);\n\n    await fetchWikispineMatch(\n      {\n        ...options,\n        endpoint,\n        maxCandidatesPerSurface: 1,\n      },\n      {\n        id: \"test\",\n        range: { end: 7, start: 0 },\n        text: \"北京大学位于北京。\",\n      },\n    );\n\n    return {\n      durationMs: Date.now() - startedAt,\n      metadata,\n      ok: true,\n      provider,\n    };\n  }\n\n  await runWikispineMatch(\n    options.command ?? \"wikispine\",\n    buildMatchArgs({\n      ...options,\n      maxCandidatesPerSurface: 1,\n    }),\n    {\n      id: \"test\",\n      range: { end: 7, start: 0 },\n      text: \"北京大学位于北京。\",\n    },\n    {},\n  );\n\n  return {\n    durationMs: Date.now() - startedAt,\n    ok: true,\n    provider,\n  };\n}\n\nasync function runWikispineMatch(\n  command: string,\n  args: readonly string[],\n  sentence: WikimatchSentence,\n  options: Pick<MatchWikispineSentenceCandidatesOptions, \"onProgress\">,\n): Promise<readonly WikispineMatchRecord[]> {\n  return await new Promise((resolve, reject) => {\n    const child = spawn(command, args, {\n      stdio: [\"pipe\", \"pipe\", \"pipe\"],\n    });\n    const progress = createWikispineProgressReporter(options.onProgress, {\n      onFailure: (error) => {\n        reject(error);\n        child.kill();\n      },\n    });\n    const parser = createWikispineNdjsonParser({\n      onMatch: (match) => {\n        progress.report({\n          coveredRangeEnd: sentence.range.start + match.end,\n        });\n      },\n    });\n    const stderr: Buffer[] = [];\n\n    child.stdout.setEncoding(\"utf8\");\n    child.stdout.on(\"data\", (chunk: string) => {\n      try {\n        parser.push(chunk);\n      } catch (error) {\n        reject(toError(error));\n        child.kill();\n      }\n    });\n    child.stderr.on(\"data\", (chunk: Buffer) => {\n      stderr.push(chunk);\n    });\n    child.on(\"error\", (error) => {\n      reject(\n        new Error(\n          formatWikispineRuntimeError(\n            `Failed to start wikispine command: ${error.message}`,\n          ),\n        ),\n      );\n    });\n    child.on(\"close\", (code) => {\n      if (code !== 0) {\n        reject(\n          new Error(\n            formatWikispineRuntimeError(\n              `wikispine match failed with exit code ${code}: ${Buffer.concat(stderr).toString(\"utf8\")}`,\n            ),\n          ),\n        );\n        return;\n      }\n\n      void (async () => {\n        try {\n          const matches = parser.finish();\n          await progress.wait();\n          resolve(matches);\n        } catch (error) {\n          reject(toError(error));\n        }\n      })();\n    });\n\n    child.stdin.end(sentence.text);\n  });\n}\n\nfunction buildMatchArgs(\n  options: Pick<\n    MatchWikispineSentenceCandidatesOptions,\n    \"dataDir\" | \"includeDisambiguation\" | \"maxCandidatesPerSurface\"\n  >,\n): string[] {\n  const args = [\"match\"];\n\n  if (options.dataDir !== undefined) {\n    args.push(\"--data-dir\", options.dataDir);\n  }\n  if (options.includeDisambiguation === false) {\n    args.push(\"--exclude-disambiguation\");\n  }\n  if (options.maxCandidatesPerSurface !== undefined) {\n    args.push(\n      \"--max-candidates-per-surface\",\n      String(options.maxCandidatesPerSurface),\n    );\n  }\n\n  return args;\n}\n\nasync function fetchWikispineMatch(\n  options: Pick<\n    MatchWikispineSentenceCandidatesOptions,\n    | \"endpoint\"\n    | \"fetch\"\n    | \"includeDisambiguation\"\n    | \"maxCandidatesPerSurface\"\n    | \"onProgress\"\n  >,\n  sentence: WikimatchSentence,\n): Promise<readonly WikispineMatchRecord[]> {\n  const endpoint = requireEndpoint(options.endpoint);\n  const response = await (options.fetch ?? fetch)(`${endpoint}/match`, {\n    body: JSON.stringify({\n      options: {\n        ...(options.includeDisambiguation === undefined\n          ? {}\n          : { include_disambiguation: options.includeDisambiguation }),\n        ...(options.maxCandidatesPerSurface === undefined\n          ? {}\n          : {\n              max_candidates_per_surface: options.maxCandidatesPerSurface,\n            }),\n      },\n      text: sentence.text,\n    }),\n    headers: {\n      accept: \"application/x-ndjson\",\n      \"content-type\": \"application/json\",\n    },\n    method: \"POST\",\n  });\n\n  if (!response.ok) {\n    throw new Error(\n      formatWikispineRuntimeError(\n        `WikiSpine fetch provider failed with HTTP ${response.status}: ${await response.text()}`,\n      ),\n    );\n  }\n\n  const progress = createWikispineProgressReporter(options.onProgress);\n  const parser = createWikispineNdjsonParser({\n    onMatch: (match) => {\n      progress.report({\n        coveredRangeEnd: sentence.range.start + match.end,\n      });\n    },\n  });\n\n  if (response.body === null) {\n    parser.push(await response.text());\n    const matches = parser.finish();\n    await progress.wait();\n    return matches;\n  }\n\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n\n  while (true) {\n    const { done, value } = await reader.read();\n    if (done) {\n      break;\n    }\n    parser.push(decoder.decode(value, { stream: true }));\n    progress.throwIfFailed();\n  }\n\n  parser.push(decoder.decode());\n  const matches = parser.finish();\n  await progress.wait();\n  return matches;\n}\n\nfunction createWikispineProgressReporter(\n  onProgress:\n    | ((progress: WikispineMatchProgress) => Promise<void> | void)\n    | undefined,\n  options?: {\n    readonly onFailure?: (error: Error) => void;\n  },\n): {\n  readonly report: (progress: WikispineMatchProgress) => void;\n  readonly throwIfFailed: () => void;\n  readonly wait: () => Promise<void>;\n} {\n  const tasks: Promise<void>[] = [];\n  let failure: Error | undefined;\n\n  function fail(error: unknown): void {\n    if (failure !== undefined) {\n      return;\n    }\n    failure = toError(error);\n    options?.onFailure?.(failure);\n  }\n\n  return {\n    report: (progress) => {\n      if (onProgress === undefined || failure !== undefined) {\n        return;\n      }\n\n      try {\n        tasks.push(Promise.resolve(onProgress(progress)).catch(fail));\n      } catch (error) {\n        fail(error);\n      }\n    },\n    throwIfFailed: () => {\n      if (failure !== undefined) {\n        throw failure;\n      }\n    },\n    wait: async () => {\n      await Promise.all(tasks);\n      if (failure !== undefined) {\n        throw failure;\n      }\n    },\n  };\n}\n\nasync function fetchWikispineMetadata(\n  endpoint: string,\n  fetchFn: typeof fetch = fetch,\n): Promise<WikispineMetadata> {\n  const ready = await fetchFn(`${endpoint}/readyz`);\n\n  if (!ready.ok) {\n    throw new Error(\n      formatWikispineRuntimeError(\n        `WikiSpine fetch provider is not ready: HTTP ${ready.status}.`,\n      ),\n    );\n  }\n\n  const response = await fetchFn(`${endpoint}/metadata`);\n\n  if (!response.ok) {\n    throw new Error(\n      formatWikispineRuntimeError(\n        `WikiSpine metadata request failed with HTTP ${response.status}.`,\n      ),\n    );\n  }\n\n  try {\n    return parseWikispineMetadata(await response.json());\n  } catch (error) {\n    if (error instanceof Error && error.message.includes(\"setup guide\")) {\n      throw error;\n    }\n\n    throw new Error(\n      formatWikispineRuntimeError(\n        `Invalid WikiSpine metadata response: ${error instanceof Error ? error.message : String(error)}`,\n      ),\n    );\n  }\n}\n\nfunction createWikispineNdjsonParser(input?: {\n  readonly onMatch?: (match: WikispineMatchRecord) => void;\n}): {\n  readonly finish: () => readonly WikispineMatchRecord[];\n  readonly push: (chunk: string) => void;\n} {\n  const matches: WikispineMatchRecord[] = [];\n  let buffer = \"\";\n\n  function parseLine(line: string): void {\n    if (line.trim() === \"\") {\n      return;\n    }\n\n    const event = parseWikispineEvent(JSON.parse(line));\n\n    if (event.type === \"match\") {\n      matches.push(event.match);\n      input?.onMatch?.(event.match);\n    }\n  }\n\n  function wrapParseError(error: unknown): Error {\n    return new Error(\n      formatWikispineRuntimeError(\n        `Invalid WikiSpine match response: ${error instanceof Error ? error.message : String(error)}`,\n      ),\n    );\n  }\n\n  return {\n    finish: () => {\n      try {\n        parseLine(buffer);\n        buffer = \"\";\n        return matches;\n      } catch (error) {\n        throw wrapParseError(error);\n      }\n    },\n    push: (chunk) => {\n      try {\n        buffer += chunk;\n        const lines = buffer.split(/\\r?\\n/u);\n        buffer = lines.pop() ?? \"\";\n\n        for (const line of lines) {\n          parseLine(line);\n        }\n      } catch (error) {\n        throw wrapParseError(error);\n      }\n    },\n  };\n}\n\nfunction parseWikispineEvent(value: unknown): WikispineEvent {\n  if (typeof value !== \"object\" || value === null) {\n    throw new Error(\"Expected wikispine event to be an object.\");\n  }\n\n  const record = value as Record<string, unknown>;\n\n  if (record.type === \"done\") {\n    return { type: \"done\" };\n  }\n  if (record.type === \"match\" && isWikispineMatchRecord(record.match)) {\n    return {\n      match: record.match,\n      type: \"match\",\n    };\n  }\n\n  throw new Error(`Unexpected wikispine event: ${JSON.stringify(value)}`);\n}\n\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\nfunction parseWikispineMetadata(value: unknown): WikispineMetadata {\n  if (typeof value !== \"object\" || value === null) {\n    throw new Error(\n      formatWikispineRuntimeError(\"Expected WikiSpine metadata.\"),\n    );\n  }\n\n  const record = value as Record<string, unknown>;\n\n  if (\n    typeof record.automaton_shard_count !== \"number\" ||\n    typeof record.format !== \"string\" ||\n    typeof record.qid_count !== \"number\" ||\n    typeof record.surface_count !== \"number\" ||\n    typeof record.surface_normalization !== \"string\"\n  ) {\n    throw new Error(formatWikispineRuntimeError(\"Invalid WikiSpine metadata.\"));\n  }\n\n  return {\n    automaton_shard_count: record.automaton_shard_count,\n    format: record.format,\n    qid_count: record.qid_count,\n    surface_count: record.surface_count,\n    surface_normalization: record.surface_normalization,\n  };\n}\n\nfunction isWikispineMatchRecord(value: unknown): value is WikispineMatchRecord {\n  if (typeof value !== \"object\" || value === null) {\n    return false;\n  }\n\n  const record = value as Record<string, unknown>;\n\n  return (\n    typeof record.end === \"number\" &&\n    Array.isArray(record.qids) &&\n    record.qids.every(isWikispineQidCandidate) &&\n    typeof record.start === \"number\" &&\n    typeof record.surface_id === \"number\"\n  );\n}\n\nfunction isWikispineQidCandidate(\n  value: unknown,\n): value is WikispineQidCandidate {\n  if (typeof value !== \"object\" || value === null) {\n    return false;\n  }\n\n  const record = value as Record<string, unknown>;\n\n  return (\n    (!(\"disambiguation\" in record) ||\n      typeof record.disambiguation === \"boolean\") &&\n    typeof record.qid === \"string\" &&\n    /^Q[1-9]\\d*$/u.test(record.qid)\n  );\n}\n\nfunction toQidOption(candidate: WikispineQidCandidate): WikimatchQidOption {\n  return {\n    isDisambiguation: candidate.disambiguation === true,\n    qid: candidate.qid,\n  };\n}\n\nfunction resolveProvider(options: {\n  readonly provider?: WikispineProvider;\n}): WikispineProvider {\n  return options.provider ?? \"cli\";\n}\n\nfunction requireEndpoint(endpoint: string | undefined): string {\n  const normalized = (endpoint ?? DEFAULT_WIKISPINE_FETCH_ENDPOINT)\n    .trim()\n    .replace(/\\/+$/u, \"\");\n\n  if (normalized === \"\") {\n    throw new Error(\n      formatWikispineRuntimeError(\n        \"WikiSpine fetch provider has no default endpoint.\",\n      ),\n    );\n  }\n\n  return normalized;\n}\n\nfunction formatWikispineRuntimeError(message: string): string {\n  return `${message}\\nWikiSpine setup guide: ${WIKISPINE_RUNTIME_GUIDE_URL}`;\n}\n"],"mappings":"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","names":["matches"]}

package/dist/wikimatch/window.d.ts

@@ -0,0 +1,6 @@
+import { BuildWikimatchWindowsOptions, WikimatchWindow } from './types.js';
+import '../wikipage/types.js';
+
+declare function buildWikimatchWindows(options: BuildWikimatchWindowsOptions): readonly WikimatchWindow[];
+
+export { buildWikimatchWindows };

package/dist/wikimatch/window.js

@@ -0,0 +1,83 @@
+import { expandRangeByWords } from "./words.js";
+import { countWikimatchCandidateOptions } from "./options.js";
+function buildWikimatchWindows(options) {
+  const groups = groupOverlappingCandidates(
+    normalizeCandidates(options.candidates ?? [])
+  );
+  const windows = [];
+  let pendingGroups = [];
+  let pendingOptionCount = 0;
+  for (const group of groups) {
+    const groupOptionCount = countGroupOptions(group);
+    if (pendingGroups.length > 0 && pendingOptionCount + groupOptionCount > options.optionBudget) {
+      windows.push(createWindow(options.text, pendingGroups, options));
+      pendingGroups = [];
+      pendingOptionCount = 0;
+    }
+    pendingGroups.push(group);
+    pendingOptionCount += groupOptionCount;
+  }
+  if (pendingGroups.length > 0) {
+    windows.push(createWindow(options.text, pendingGroups, options));
+  }
+  return windows;
+}
+function countGroupOptions(group) {
+  return group.candidates.reduce(
+    (total, candidate) => total + countWikimatchCandidateOptions(candidate),
+    0
+  );
+}
+function createWindow(text, groups, options) {
+  const groupStart = Math.min(...groups.map((group) => group.range.start));
+  const groupEnd = Math.max(...groups.map((group) => group.range.end));
+  const expandedRange = expandRangeByWords({
+    rangeEnd: groupEnd,
+    rangeStart: groupStart,
+    text,
+    words: options.contextWords
+  });
+  return {
+    baseOffset: expandedRange.start,
+    candidates: groups.flatMap((group) => group.candidates),
+    groups: groups.map((group, index) => ({
+      candidateIds: group.candidates.map((candidate) => candidate.id),
+      id: `g${index + 1}`,
+      range: group.range
+    })),
+    text: text.slice(expandedRange.start, expandedRange.end)
+  };
+}
+function groupOverlappingCandidates(candidates) {
+  const groups = [];
+  let current;
+  for (const candidate of candidates) {
+    if (current === void 0 || candidate.range.start >= current.range.end) {
+      current = {
+        candidates: [candidate],
+        range: candidate.range
+      };
+      groups.push(current);
+      continue;
+    }
+    current = {
+      candidates: [...current.candidates, candidate],
+      range: {
+        end: Math.max(current.range.end, candidate.range.end),
+        start: Math.min(current.range.start, candidate.range.start)
+      }
+    };
+    groups[groups.length - 1] = current;
+  }
+  return groups;
+}
+function normalizeCandidates(candidates) {
+  return candidates.filter((candidate) => candidate.range.start < candidate.range.end).sort(compareCandidate);
+}
+function compareCandidate(left, right) {
+  return left.range.start - right.range.start || right.range.end - left.range.end || left.id.localeCompare(right.id);
+}
+export {
+  buildWikimatchWindows
+};
+//# sourceMappingURL=window.js.map

package/dist/wikimatch/window.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikimatch/window.ts"],"sourcesContent":["import { expandRangeByWords } from \"./words.js\";\nimport { countWikimatchCandidateOptions } from \"./options.js\";\nimport type {\n  BuildWikimatchWindowsOptions,\n  WikimatchCandidate,\n  WikimatchWindow,\n} from \"./types.js\";\n\ninterface CandidateGroup {\n  readonly candidates: readonly WikimatchCandidate[];\n  readonly range: {\n    readonly end: number;\n    readonly start: number;\n  };\n}\n\nexport function buildWikimatchWindows(\n  options: BuildWikimatchWindowsOptions,\n): readonly WikimatchWindow[] {\n  const groups = groupOverlappingCandidates(\n    normalizeCandidates(options.candidates ?? []),\n  );\n  const windows: WikimatchWindow[] = [];\n  let pendingGroups: CandidateGroup[] = [];\n  let pendingOptionCount = 0;\n\n  for (const group of groups) {\n    const groupOptionCount = countGroupOptions(group);\n\n    if (\n      pendingGroups.length > 0 &&\n      pendingOptionCount + groupOptionCount > options.optionBudget\n    ) {\n      windows.push(createWindow(options.text, pendingGroups, options));\n      pendingGroups = [];\n      pendingOptionCount = 0;\n    }\n\n    pendingGroups.push(group);\n    pendingOptionCount += groupOptionCount;\n  }\n\n  if (pendingGroups.length > 0) {\n    windows.push(createWindow(options.text, pendingGroups, options));\n  }\n\n  return windows;\n}\n\nfunction countGroupOptions(group: CandidateGroup): number {\n  return group.candidates.reduce(\n    (total, candidate) => total + countWikimatchCandidateOptions(candidate),\n    0,\n  );\n}\n\nfunction createWindow(\n  text: string,\n  groups: readonly CandidateGroup[],\n  options: BuildWikimatchWindowsOptions,\n): WikimatchWindow {\n  const groupStart = Math.min(...groups.map((group) => group.range.start));\n  const groupEnd = Math.max(...groups.map((group) => group.range.end));\n  const expandedRange = expandRangeByWords({\n    rangeEnd: groupEnd,\n    rangeStart: groupStart,\n    text,\n    words: options.contextWords,\n  });\n\n  return {\n    baseOffset: expandedRange.start,\n    candidates: groups.flatMap((group) => group.candidates),\n    groups: groups.map((group, index) => ({\n      candidateIds: group.candidates.map((candidate) => candidate.id),\n      id: `g${index + 1}`,\n      range: group.range,\n    })),\n    text: text.slice(expandedRange.start, expandedRange.end),\n  };\n}\n\nfunction groupOverlappingCandidates(\n  candidates: readonly WikimatchCandidate[],\n): readonly CandidateGroup[] {\n  const groups: CandidateGroup[] = [];\n  let current: CandidateGroup | undefined;\n\n  for (const candidate of candidates) {\n    if (current === undefined || candidate.range.start >= current.range.end) {\n      current = {\n        candidates: [candidate],\n        range: candidate.range,\n      };\n      groups.push(current);\n      continue;\n    }\n\n    current = {\n      candidates: [...current.candidates, candidate],\n      range: {\n        end: Math.max(current.range.end, candidate.range.end),\n        start: Math.min(current.range.start, candidate.range.start),\n      },\n    };\n    groups[groups.length - 1] = current;\n  }\n\n  return groups;\n}\n\nfunction normalizeCandidates(\n  candidates: readonly WikimatchCandidate[],\n): readonly WikimatchCandidate[] {\n  return candidates\n    .filter((candidate) => candidate.range.start < candidate.range.end)\n    .sort(compareCandidate);\n}\n\nfunction compareCandidate(\n  left: WikimatchCandidate,\n  right: WikimatchCandidate,\n): number {\n  return (\n    left.range.start - right.range.start ||\n    right.range.end - left.range.end ||\n    left.id.localeCompare(right.id)\n  );\n}\n"],"mappings":"AAAA,SAAS,0BAA0B;AACnC,SAAS,sCAAsC;AAexC,SAAS,sBACd,SAC4B;AAC5B,QAAM,SAAS;AAAA,IACb,oBAAoB,QAAQ,cAAc,CAAC,CAAC;AAAA,EAC9C;AACA,QAAM,UAA6B,CAAC;AACpC,MAAI,gBAAkC,CAAC;AACvC,MAAI,qBAAqB;AAEzB,aAAW,SAAS,QAAQ;AAC1B,UAAM,mBAAmB,kBAAkB,KAAK;AAEhD,QACE,cAAc,SAAS,KACvB,qBAAqB,mBAAmB,QAAQ,cAChD;AACA,cAAQ,KAAK,aAAa,QAAQ,MAAM,eAAe,OAAO,CAAC;AAC/D,sBAAgB,CAAC;AACjB,2BAAqB;AAAA,IACvB;AAEA,kBAAc,KAAK,KAAK;AACxB,0BAAsB;AAAA,EACxB;AAEA,MAAI,cAAc,SAAS,GAAG;AAC5B,YAAQ,KAAK,aAAa,QAAQ,MAAM,eAAe,OAAO,CAAC;AAAA,EACjE;AAEA,SAAO;AACT;AAEA,SAAS,kBAAkB,OAA+B;AACxD,SAAO,MAAM,WAAW;AAAA,IACtB,CAAC,OAAO,cAAc,QAAQ,+BAA+B,SAAS;AAAA,IACtE;AAAA,EACF;AACF;AAEA,SAAS,aACP,MACA,QACA,SACiB;AACjB,QAAM,aAAa,KAAK,IAAI,GAAG,OAAO,IAAI,CAAC,UAAU,MAAM,MAAM,KAAK,CAAC;AACvE,QAAM,WAAW,KAAK,IAAI,GAAG,OAAO,IAAI,CAAC,UAAU,MAAM,MAAM,GAAG,CAAC;AACnE,QAAM,gBAAgB,mBAAmB;AAAA,IACvC,UAAU;AAAA,IACV,YAAY;AAAA,IACZ;AAAA,IACA,OAAO,QAAQ;AAAA,EACjB,CAAC;AAED,SAAO;AAAA,IACL,YAAY,cAAc;AAAA,IAC1B,YAAY,OAAO,QAAQ,CAAC,UAAU,MAAM,UAAU;AAAA,IACtD,QAAQ,OAAO,IAAI,CAAC,OAAO,WAAW;AAAA,MACpC,cAAc,MAAM,WAAW,IAAI,CAAC,cAAc,UAAU,EAAE;AAAA,MAC9D,IAAI,IAAI,QAAQ,CAAC;AAAA,MACjB,OAAO,MAAM;AAAA,IACf,EAAE;AAAA,IACF,MAAM,KAAK,MAAM,cAAc,OAAO,cAAc,GAAG;AAAA,EACzD;AACF;AAEA,SAAS,2BACP,YAC2B;AAC3B,QAAM,SAA2B,CAAC;AAClC,MAAI;AAEJ,aAAW,aAAa,YAAY;AAClC,QAAI,YAAY,UAAa,UAAU,MAAM,SAAS,QAAQ,MAAM,KAAK;AACvE,gBAAU;AAAA,QACR,YAAY,CAAC,SAAS;AAAA,QACtB,OAAO,UAAU;AAAA,MACnB;AACA,aAAO,KAAK,OAAO;AACnB;AAAA,IACF;AAEA,cAAU;AAAA,MACR,YAAY,CAAC,GAAG,QAAQ,YAAY,SAAS;AAAA,MAC7C,OAAO;AAAA,QACL,KAAK,KAAK,IAAI,QAAQ,MAAM,KAAK,UAAU,MAAM,GAAG;AAAA,QACpD,OAAO,KAAK,IAAI,QAAQ,MAAM,OAAO,UAAU,MAAM,KAAK;AAAA,MAC5D;AAAA,IACF;AACA,WAAO,OAAO,SAAS,CAAC,IAAI;AAAA,EAC9B;AAEA,SAAO;AACT;AAEA,SAAS,oBACP,YAC+B;AAC/B,SAAO,WACJ,OAAO,CAAC,cAAc,UAAU,MAAM,QAAQ,UAAU,MAAM,GAAG,EACjE,KAAK,gBAAgB;AAC1B;AAEA,SAAS,iBACP,MACA,OACQ;AACR,SACE,KAAK,MAAM,QAAQ,MAAM,MAAM,SAC/B,MAAM,MAAM,MAAM,KAAK,MAAM,OAC7B,KAAK,GAAG,cAAc,MAAM,EAAE;AAElC;","names":[]}

package/dist/wikimatch/words.d.ts

@@ -0,0 +1,16 @@
+interface WordBoundary {
+    readonly end: number;
+    readonly start: number;
+}
+declare function listWordBoundaries(text: string): readonly WordBoundary[];
+declare function expandRangeByWords(input: {
+    readonly rangeEnd: number;
+    readonly rangeStart: number;
+    readonly text: string;
+    readonly words: number;
+}): {
+    readonly end: number;
+    readonly start: number;
+};
+
+export { type WordBoundary, expandRangeByWords, listWordBoundaries };

package/dist/wikimatch/words.js

@@ -0,0 +1,66 @@
+function listWordBoundaries(text) {
+  const segmenter = new Intl.Segmenter(void 0, {
+    granularity: "word"
+  });
+  const graphemeSegmenter = new Intl.Segmenter(void 0, {
+    granularity: "grapheme"
+  });
+  const words = [];
+  for (const segment of segmenter.segment(text)) {
+    if ("isWordLike" in segment && segment.isWordLike) {
+      words.push({
+        end: segment.index + segment.segment.length,
+        start: segment.index
+      });
+    }
+  }
+  if (words.length > 0) {
+    return words;
+  }
+  return [...graphemeSegmenter.segment(text)].filter((segment) => segment.segment.trim() !== "").map((segment) => ({
+    end: segment.index + segment.segment.length,
+    start: segment.index
+  }));
+}
+function expandRangeByWords(input) {
+  const wordBoundaries = listWordBoundaries(input.text);
+  if (wordBoundaries.length === 0) {
+    return {
+      end: input.text.length,
+      start: 0
+    };
+  }
+  const firstWordIndex = findWordIndexAtOrAfter(
+    wordBoundaries,
+    input.rangeStart
+  );
+  const lastWordIndex = findWordIndexBeforeOrAt(wordBoundaries, input.rangeEnd);
+  const halfBudget = Math.max(0, Math.floor(input.words / 2));
+  const startIndex = Math.max(0, firstWordIndex - halfBudget);
+  const endIndex = Math.min(
+    wordBoundaries.length - 1,
+    lastWordIndex + halfBudget
+  );
+  return {
+    end: wordBoundaries[endIndex]?.end ?? input.text.length,
+    start: wordBoundaries[startIndex]?.start ?? 0
+  };
+}
+function findWordIndexAtOrAfter(words, offset) {
+  const matched = words.findIndex((word) => word.end > offset);
+  return matched === -1 ? words.length - 1 : matched;
+}
+function findWordIndexBeforeOrAt(words, offset) {
+  for (let index = words.length - 1; index >= 0; index -= 1) {
+    const word = words[index];
+    if (word !== void 0 && word.start < offset) {
+      return index;
+    }
+  }
+  return 0;
+}
+export {
+  expandRangeByWords,
+  listWordBoundaries
+};
+//# sourceMappingURL=words.js.map

package/dist/wikimatch/words.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wikimatch/words.ts"],"sourcesContent":["export interface WordBoundary {\n  readonly end: number;\n  readonly start: number;\n}\n\nexport function listWordBoundaries(text: string): readonly WordBoundary[] {\n  const segmenter = new Intl.Segmenter(undefined, {\n    granularity: \"word\",\n  });\n  const graphemeSegmenter = new Intl.Segmenter(undefined, {\n    granularity: \"grapheme\",\n  });\n  const words: WordBoundary[] = [];\n\n  for (const segment of segmenter.segment(text)) {\n    if (\"isWordLike\" in segment && segment.isWordLike) {\n      words.push({\n        end: segment.index + segment.segment.length,\n        start: segment.index,\n      });\n    }\n  }\n\n  if (words.length > 0) {\n    return words;\n  }\n\n  return [...graphemeSegmenter.segment(text)]\n    .filter((segment) => segment.segment.trim() !== \"\")\n    .map((segment) => ({\n      end: segment.index + segment.segment.length,\n      start: segment.index,\n    }));\n}\n\nexport function expandRangeByWords(input: {\n  readonly rangeEnd: number;\n  readonly rangeStart: number;\n  readonly text: string;\n  readonly words: number;\n}): { readonly end: number; readonly start: number } {\n  const wordBoundaries = listWordBoundaries(input.text);\n\n  if (wordBoundaries.length === 0) {\n    return {\n      end: input.text.length,\n      start: 0,\n    };\n  }\n\n  const firstWordIndex = findWordIndexAtOrAfter(\n    wordBoundaries,\n    input.rangeStart,\n  );\n  const lastWordIndex = findWordIndexBeforeOrAt(wordBoundaries, input.rangeEnd);\n  const halfBudget = Math.max(0, Math.floor(input.words / 2));\n  const startIndex = Math.max(0, firstWordIndex - halfBudget);\n  const endIndex = Math.min(\n    wordBoundaries.length - 1,\n    lastWordIndex + halfBudget,\n  );\n\n  return {\n    end: wordBoundaries[endIndex]?.end ?? input.text.length,\n    start: wordBoundaries[startIndex]?.start ?? 0,\n  };\n}\n\nfunction findWordIndexAtOrAfter(\n  words: readonly WordBoundary[],\n  offset: number,\n): number {\n  const matched = words.findIndex((word) => word.end > offset);\n\n  return matched === -1 ? words.length - 1 : matched;\n}\n\nfunction findWordIndexBeforeOrAt(\n  words: readonly WordBoundary[],\n  offset: number,\n): number {\n  for (let index = words.length - 1; index >= 0; index -= 1) {\n    const word = words[index];\n\n    if (word !== undefined && word.start < offset) {\n      return index;\n    }\n  }\n\n  return 0;\n}\n"],"mappings":"AAKO,SAAS,mBAAmB,MAAuC;AACxE,QAAM,YAAY,IAAI,KAAK,UAAU,QAAW;AAAA,IAC9C,aAAa;AAAA,EACf,CAAC;AACD,QAAM,oBAAoB,IAAI,KAAK,UAAU,QAAW;AAAA,IACtD,aAAa;AAAA,EACf,CAAC;AACD,QAAM,QAAwB,CAAC;AAE/B,aAAW,WAAW,UAAU,QAAQ,IAAI,GAAG;AAC7C,QAAI,gBAAgB,WAAW,QAAQ,YAAY;AACjD,YAAM,KAAK;AAAA,QACT,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AAAA,QACrC,OAAO,QAAQ;AAAA,MACjB,CAAC;AAAA,IACH;AAAA,EACF;AAEA,MAAI,MAAM,SAAS,GAAG;AACpB,WAAO;AAAA,EACT;AAEA,SAAO,CAAC,GAAG,kBAAkB,QAAQ,IAAI,CAAC,EACvC,OAAO,CAAC,YAAY,QAAQ,QAAQ,KAAK,MAAM,EAAE,EACjD,IAAI,CAAC,aAAa;AAAA,IACjB,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AAAA,IACrC,OAAO,QAAQ;AAAA,EACjB,EAAE;AACN;AAEO,SAAS,mBAAmB,OAKkB;AACnD,QAAM,iBAAiB,mBAAmB,MAAM,IAAI;AAEpD,MAAI,eAAe,WAAW,GAAG;AAC/B,WAAO;AAAA,MACL,KAAK,MAAM,KAAK;AAAA,MAChB,OAAO;AAAA,IACT;AAAA,EACF;AAEA,QAAM,iBAAiB;AAAA,IACrB;AAAA,IACA,MAAM;AAAA,EACR;AACA,QAAM,gBAAgB,wBAAwB,gBAAgB,MAAM,QAAQ;AAC5E,QAAM,aAAa,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,QAAQ,CAAC,CAAC;AAC1D,QAAM,aAAa,KAAK,IAAI,GAAG,iBAAiB,UAAU;AAC1D,QAAM,WAAW,KAAK;AAAA,IACpB,eAAe,SAAS;AAAA,IACxB,gBAAgB;AAAA,EAClB;AAEA,SAAO;AAAA,IACL,KAAK,eAAe,QAAQ,GAAG,OAAO,MAAM,KAAK;AAAA,IACjD,OAAO,eAAe,UAAU,GAAG,SAAS;AAAA,EAC9C;AACF;AAEA,SAAS,uBACP,OACA,QACQ;AACR,QAAM,UAAU,MAAM,UAAU,CAAC,SAAS,KAAK,MAAM,MAAM;AAE3D,SAAO,YAAY,KAAK,MAAM,SAAS,IAAI;AAC7C;AAEA,SAAS,wBACP,OACA,QACQ;AACR,WAAS,QAAQ,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG;AACzD,UAAM,OAAO,MAAM,KAAK;AAExB,QAAI,SAAS,UAAa,KAAK,QAAQ,QAAQ;AAC7C,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/dist/wikipage/cache.d.ts

@@ -0,0 +1,18 @@
+import { Database } from '../document/database.js';
+import { GcContext, GcJobResult } from '../gc/types.js';
+import { CachedQidRecord, CachedDisambiguationRecord } from './types.js';
+import 'sqlite3';
+
+declare class WikipageCache {
+    #private;
+    constructor(database: Database);
+    static open(path?: string): Promise<WikipageCache>;
+    close(): Promise<void>;
+    getQids(qids: readonly string[], language: string): Promise<ReadonlyMap<string, CachedQidRecord>>;
+    putQids(records: readonly CachedQidRecord[], language: string): Promise<void>;
+    getDisambiguations(qids: readonly string[], wiki: string): Promise<ReadonlyMap<string, CachedDisambiguationRecord>>;
+    putDisambiguations(records: readonly CachedDisambiguationRecord[], wiki: string): Promise<void>;
+}
+declare function runWikipageCacheGc(context: GcContext): Promise<GcJobResult>;
+
+export { WikipageCache, runWikipageCacheGc };