@wei840222/qmd 2026.8.23

package/dist/search/jieba-loader.d.ts

@@ -0,0 +1,23 @@
+export interface JiebaDiagnostic {
+    readonly code: "JIEBA_NATIVE_UNAVAILABLE";
+    readonly message: "Chinese word segmentation is unavailable for this runtime.";
+    readonly runtime: string;
+    readonly remediation: "Reinstall @node-rs/jieba with optional dependencies enabled on a supported OS, architecture, and libc.";
+}
+export type JiebaCapability = {
+    readonly available: true;
+    readonly cut: (text: string, hmm?: boolean) => string[];
+} | {
+    readonly available: false;
+    readonly diagnostic: JiebaDiagnostic;
+};
+export type JiebaModuleImporter = (specifier: string) => Promise<unknown>;
+export declare function createJiebaUnavailableCapability(): Extract<JiebaCapability, {
+    available: false;
+}>;
+export declare function createJiebaLoader(importModule?: JiebaModuleImporter): (userDictionary?: Uint8Array) => Promise<JiebaCapability>;
+export declare const loadJiebaCapability: (userDictionary?: Uint8Array) => Promise<JiebaCapability>;
+/** @internal Override the synchronous mutation analyzer in tests. */
+export declare function setSynchronousJiebaCapabilityForTests(capability?: JiebaCapability): void;
+/** Load the same analyzer and versioned dictionary for synchronous mutation paths. */
+export declare function loadJiebaCapabilitySync(userDictionary?: Uint8Array): JiebaCapability;

package/dist/search/jieba-loader.js

@@ -0,0 +1,79 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+function asRecord(value) {
+    return (typeof value === "object" && value !== null) || typeof value === "function"
+        ? value
+        : null;
+}
+export function createJiebaUnavailableCapability() {
+    const diagnostic = Object.freeze({
+        code: "JIEBA_NATIVE_UNAVAILABLE",
+        message: "Chinese word segmentation is unavailable for this runtime.",
+        runtime: `${process.platform}-${process.arch}`,
+        remediation: "Reinstall @node-rs/jieba with optional dependencies enabled on a supported OS, architecture, and libc.",
+    });
+    return Object.freeze({
+        available: false,
+        diagnostic,
+    });
+}
+function initializeCapability(packageModule, userDictionary) {
+    const packageRecord = asRecord(packageModule);
+    const Jieba = (packageRecord?.Jieba ?? null);
+    if (!Jieba
+        || typeof Jieba.withDict !== "function") {
+        return createJiebaUnavailableCapability();
+    }
+    const instance = Jieba.withDict(readFileSync(new URL("./zh-dict.txt", import.meta.url)));
+    if (!instance
+        || typeof instance.cut !== "function"
+        || typeof instance.loadDict !== "function") {
+        return createJiebaUnavailableCapability();
+    }
+    if (userDictionary && userDictionary.byteLength > 0) {
+        instance.loadDict(userDictionary);
+    }
+    return Object.freeze({
+        available: true,
+        cut: (text, hmm = false) => instance.cut(text, hmm),
+    });
+}
+async function loadCapability(importModule, userDictionary) {
+    try {
+        const packageModule = await importModule("@node-rs/jieba");
+        return initializeCapability(packageModule, userDictionary);
+    }
+    catch {
+        return createJiebaUnavailableCapability();
+    }
+}
+export function createJiebaLoader(importModule = specifier => import(specifier)) {
+    let cached;
+    return (userDictionary) => {
+        if (userDictionary)
+            return loadCapability(importModule, userDictionary);
+        cached ??= loadCapability(importModule);
+        return cached;
+    };
+}
+export const loadJiebaCapability = createJiebaLoader();
+const require = createRequire(import.meta.url);
+let synchronousCapability;
+/** @internal Override the synchronous mutation analyzer in tests. */
+export function setSynchronousJiebaCapabilityForTests(capability) {
+    synchronousCapability = capability;
+}
+/** Load the same analyzer and versioned dictionary for synchronous mutation paths. */
+export function loadJiebaCapabilitySync(userDictionary) {
+    if (synchronousCapability && !userDictionary)
+        return synchronousCapability;
+    try {
+        const cap = initializeCapability(require("@node-rs/jieba"), userDictionary);
+        if (!userDictionary)
+            synchronousCapability = cap;
+        return cap;
+    }
+    catch {
+        return createJiebaUnavailableCapability();
+    }
+}

package/dist/search/query-expansion.d.ts

@@ -0,0 +1,23 @@
+export type ExpansionMode = "auto" | "force" | "skip";
+export type ExpansionAction = "expand" | "skip";
+export type ExpansionReason = "cjk-default" | "strong-signal" | "explicit-skip" | "explicit-force" | "auto-expand";
+export type ExpansionDirective = {
+    directive: "force" | "skip" | null;
+    query: string;
+};
+export type ExpansionDecision = {
+    action: ExpansionAction;
+    reason: ExpansionReason;
+    query: string;
+};
+export declare class ExpansionPolicyError extends Error {
+    readonly reason: "conflicting-directives";
+    constructor(reason: "conflicting-directives", message: string);
+}
+export declare function parseExpansionDirective(input: string): ExpansionDirective;
+export declare function resolveExpansionPolicy(options: {
+    query: string;
+    mode: ExpansionMode;
+    strongSignal: boolean;
+    allowCjkExpand?: boolean;
+}): ExpansionDecision;

package/dist/search/query-expansion.js

@@ -0,0 +1,43 @@
+import { containsCjk } from "./cjk-analyzer.js";
+export class ExpansionPolicyError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "ExpansionPolicyError";
+        this.reason = reason;
+    }
+}
+export function parseExpansionDirective(input) {
+    const trimmed = input.trim();
+    const match = /^(lex|expand)\s*:\s*(.*)$/isu.exec(trimmed);
+    if (!match)
+        return { directive: null, query: trimmed };
+    const query = (match[2] ?? "").trim();
+    if (!query)
+        throw new Error(`${match[1]?.toLowerCase()}: requires a non-empty query`);
+    return {
+        directive: match[1]?.toLowerCase() === "lex" ? "skip" : "force",
+        query,
+    };
+}
+export function resolveExpansionPolicy(options) {
+    const parsed = parseExpansionDirective(options.query);
+    if (!parsed.query)
+        throw new Error("query must not be empty");
+    if (options.mode === "force" && parsed.directive === "skip") {
+        throw new ExpansionPolicyError("conflicting-directives", "conflicting expansion directives: force cannot be combined with lex:");
+    }
+    if (options.mode === "skip" || parsed.directive === "skip") {
+        return { action: "skip", reason: "explicit-skip", query: parsed.query };
+    }
+    if (options.mode === "force" || parsed.directive === "force") {
+        return { action: "expand", reason: "explicit-force", query: parsed.query };
+    }
+    if (containsCjk(parsed.query) && !options.allowCjkExpand) {
+        return { action: "skip", reason: "cjk-default", query: parsed.query };
+    }
+    if (options.strongSignal) {
+        return { action: "skip", reason: "strong-signal", query: parsed.query };
+    }
+    return { action: "expand", reason: "auto-expand", query: parsed.query };
+}