ko-qmd 2.8.3-ko.10

package/bin/qmd

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// 2>/dev/null; if command -v node >/dev/null 2>&1; then exec node "$0" "$@"; else exec bun "$0" "$@"; fi
+// Cross-platform launcher for qmd.
+//
+// Previously this was a POSIX shell script with `#!/bin/sh`, which meant npm
+// on Windows generated shims that tried to route through `/bin/sh` — a path
+// that doesn't exist on Windows, so `qmd` failed immediately after a global
+// install. Rewriting the launcher in Node.js lets npm generate native
+// cmd/ps1/sh shims that invoke `node` directly on every platform.
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Resolve symlinks so global installs (npm link / npm install -g) can find
+// the actual package directory instead of the global bin directory.
+const self = realpathSync(fileURLToPath(import.meta.url));
+const pkgDir = resolve(dirname(self), "..");
+const jsEntry = resolve(pkgDir, "dist/cli/qmd.js");
+const tsEntry = resolve(pkgDir, "src/cli/qmd.ts");
+
+// MCP stdio reserves stdout exclusively for JSON-RPC frames. node-llama-cpp
+// / llama.cpp / ggml can write native logs directly to stdout before JS-level
+// log handlers are attached, so seed the native quiet env before Node/Bun imports
+// the CLI and its LLM modules. Preserve explicit user values when provided.
+if (process.argv[2] === "mcp") {
+  process.env.LLAMA_LOG_LEVEL = process.env.LLAMA_LOG_LEVEL || "error";
+  process.env.GGML_LOG_LEVEL = process.env.GGML_LOG_LEVEL || "error";
+  process.env.GGML_BACKEND_SILENT = process.env.GGML_BACKEND_SILENT || "1";
+}
+
+// libggml-metal on macOS uses "residency sets" to keep allocated model memory
+// resident across inference requests (180-second keep_alive timer). The
+// process-static device destructor that runs during libc exit() asserts the
+// residency set is empty (ggml-org/llama.cpp#22593); the keep_alive hasn't
+// expired by exit, so the assertion fails and ggml_abort dumps a multi-kB
+// stack trace to stderr even when the user-visible results were already
+// emitted correctly. No JS-side dispose can prevent it because the static
+// destructor runs in __cxa_finalize_ranges, after every JS-reachable cleanup.
+//
+// For QMD's short-lived CLI workflow, residency sets provide no observable
+// performance benefit (subsequent requests don't reuse the warm mapping —
+// measured: identical wall time with and without on M3 Pro), so disable them
+// by default on darwin. The env var must be set BEFORE the native llama.cpp
+// binding loads, which is why it lives here in the launcher rather than in
+// the JS entry point. Opt back in with QMD_METAL_KEEP_RESIDENCY=1 if you
+// run long-lived qmd processes (the MCP daemon may benefit on hot reload)
+// or are triaging an upstream Metal teardown fix.
+if (process.platform === "darwin" && process.env.QMD_METAL_KEEP_RESIDENCY !== "1") {
+  process.env.GGML_METAL_NO_RESIDENCY = process.env.GGML_METAL_NO_RESIDENCY || "1";
+}
+
+function hasBun() {
+  try {
+    const res = spawnSync("bun", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// In published packages, bin/qmd must run dist/. In a git checkout, however,
+// dist/ is often ignored and can be stale after git reset or branch switches.
+// Prefer source mode only for checkouts so ./bin/qmd reflects the checked-out
+// source without changing packaged/runtime behavior.
+//
+// Critical: source-mode detection must NOT trigger when a package manager
+// installed us. `pnpm install -g .` (and `npm install -g .`) copy the entire
+// working tree — including .git/, bun.lock, package-lock.json, src/, and even
+// node_modules/ — into <prefix>/node_modules/@tobilu/qmd/, so .git and a
+// lockfile being present is not a reliable "this is a working tree" signal.
+// What IS reliable: a package-manager install always lands the package
+// directory inside a `node_modules/` segment; a bare working-tree checkout
+// (with `bun link` or a direct path invocation) does not. Gate source mode
+// on that. Allow QMD_SOURCE_MODE=1 / =0 as an explicit override for the
+// rare case where the heuristic disagrees with the user.
+const sourceOverride = process.env.QMD_SOURCE_MODE;
+const looksInstalled = pkgDir.split("/").includes("node_modules");
+const sourceAllowed = sourceOverride === "1"
+  || (sourceOverride !== "0" && !looksInstalled);
+
+let useSourceMode = false;
+let sourceRunner = null;
+let sourceArgs = [];
+
+if (sourceAllowed && existsSync(resolve(pkgDir, ".git")) && existsSync(tsEntry)) {
+  // Lockfile-driven runner selection — mirror the dist-mode logic below so
+  // source mode picks the same runtime the user's deps were installed for.
+  // package-lock.json wins over bun.lock when both are present: pnpm/npm
+  // installs ship the Node-ABI native modules (better-sqlite3, sqlite-vec),
+  // and running Bun against them produces ABI mismatches. This also fixes
+  // pnpm-global installs, which copy the whole working tree — including .git
+  // and bun.lock — into the install dir and used to route through Bun even
+  // when the user installed via npm/pnpm.
+  const hasNpmLock = existsSync(resolve(pkgDir, "package-lock.json"));
+  const hasBunLock = existsSync(resolve(pkgDir, "bun.lock")) || existsSync(resolve(pkgDir, "bun.lockb"));
+  const tsxEntry = resolve(pkgDir, "node_modules/tsx/dist/cli.mjs");
+  const tsxAvailable = existsSync(tsxEntry);
+
+  if (hasNpmLock && tsxAvailable) {
+    useSourceMode = true;
+    sourceRunner = "node";
+    sourceArgs = [tsxEntry, tsEntry, ...process.argv.slice(2)];
+  } else if (hasBunLock && hasBun()) {
+    useSourceMode = true;
+    sourceRunner = "bun";
+    sourceArgs = [tsEntry, ...process.argv.slice(2)];
+  } else if (tsxAvailable) {
+    useSourceMode = true;
+    sourceRunner = "node";
+    sourceArgs = [tsxEntry, tsEntry, ...process.argv.slice(2)];
+  }
+}
+
+if (!useSourceMode && !existsSync(jsEntry)) {
+  console.error(`qmd is not built: missing ${jsEntry}`);
+  console.error("Run: bun install && bun run build");
+  console.error("Or:  npm install && npm run build");
+  console.error("After building, run: qmd doctor");
+  process.exit(1);
+}
+
+// Detect the package manager that installed dependencies by checking lockfiles.
+// $BUN_INSTALL is intentionally NOT checked — it only indicates that bun exists
+// on the system, not that it was used to install this package (see #361).
+//
+// package-lock.json takes priority: if it exists, npm installed the native
+// modules for Node. The repo ships bun.lock, so without this check, source
+// builds that use npm would be incorrectly routed to bun, causing ABI
+// mismatches with better-sqlite3 / sqlite-vec (see #381).
+//
+// Package-manager installs keep their lockfile at the install root, above
+// node_modules/ — never inside the package directory itself. A bun global
+// install writes $BUN_INSTALL/install/global/bun.lock while the package
+// lands in .../install/global/node_modules/@tobilu/qmd/, so the package-dir
+// checks below can't match and qmd would run under whatever node is first
+// on PATH. The native modules were built by the installing runtime; after
+// the next Node major upgrade they fail to load (ERR_DLOPEN_FAILED,
+// NODE_MODULE_VERSION mismatch). Apply the same npm-priority rule at the
+// install root when the package directory itself has no lockfile.
+const pathParts = pkgDir.split(sep);
+const nodeModulesIndex = pathParts.lastIndexOf("node_modules");
+const installRoot = nodeModulesIndex === -1 ? null : pathParts.slice(0, nodeModulesIndex).join(sep);
+const hasRootNpmLock = installRoot !== null && existsSync(resolve(installRoot, "package-lock.json"));
+const hasRootBunLock = installRoot !== null
+  && (existsSync(resolve(installRoot, "bun.lock")) || existsSync(resolve(installRoot, "bun.lockb")));
+
+let runnerName = "node";
+if (existsSync(resolve(pkgDir, "package-lock.json"))) {
+  runnerName = "node";
+} else if (existsSync(resolve(pkgDir, "bun.lock")) || existsSync(resolve(pkgDir, "bun.lockb"))) {
+  runnerName = "bun";
+} else if (hasRootNpmLock) {
+  runnerName = "node";
+} else if (hasRootBunLock) {
+  runnerName = "bun";
+} else {
+  runnerName = "node";
+}
+
+const selected = useSourceMode ? sourceRunner : (runnerName === "node" ? "node" : "bun");
+// Pin Node to the binary that launched this trampoline. Native addons
+// (better-sqlite3) are compiled for that install's ABI; spawning PATH
+// `node` picks up nvm/fnm/mise shims in the project directory and fails
+// with NODE_MODULE_VERSION / ERR_DLOPEN_FAILED (leftover from #577; #319).
+// If the trampoline itself is running under bun (`bun bin/qmd`), keep
+// PATH `node` so we don't load Node-ABI addons into bun.
+const runner = selected === "node" && typeof process.versions.bun !== "string"
+  ? process.execPath
+  : selected;
+const args = useSourceMode ? sourceArgs : [jsEntry, ...process.argv.slice(2)];
+const needsShell = (runner === "bun") && process.platform === "win32";
+
+const child = spawn(runner, args, {
+  stdio: "inherit",
+  shell: needsShell,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});
+
+child.on("error", (err) => {
+  const name = useSourceMode ? sourceRunner : runnerName;
+  console.error(`qmd: failed to launch ${name}: ${err.message}`);
+  process.exit(1);
+});

package/dist/ast.d.ts

@@ -0,0 +1,65 @@
+/**
+ * AST-aware chunking support via web-tree-sitter.
+ *
+ * Provides language detection, AST break point extraction for supported
+ * code file types, and a stub for future symbol extraction.
+ *
+ * All functions degrade gracefully: parse failures or unsupported languages
+ * return empty arrays, falling back to regex-only chunking.
+ *
+ * ## Dependency Note
+ *
+ * Grammar packages (tree-sitter-typescript, etc.) are listed as
+ * optionalDependencies with pinned versions. They ship native prebuilds
+ * and source files (~72 MB total) but QMD only uses the .wasm files
+ * (~5 MB). If install size becomes a concern, the .wasm files can be
+ * bundled directly in the repo (e.g. assets/grammars/) and resolved
+ * via import.meta.url instead of require.resolve(), eliminating the
+ * grammar packages entirely.
+ */
+import type { BreakPoint } from "./store.js";
+export type SupportedLanguage = "typescript" | "tsx" | "javascript" | "python" | "go" | "rust";
+/**
+ * Detect language from file path extension.
+ * Returns null for unsupported or unknown extensions (including .md).
+ */
+export declare function detectLanguage(filepath: string): SupportedLanguage | null;
+export declare function formatGrammarLoadError(language: SupportedLanguage, err: unknown): string;
+/**
+ * Parse a source file and return break points at AST node boundaries.
+ *
+ * Returns an empty array for unsupported languages, parse failures,
+ * or grammar loading failures. Never throws.
+ *
+ * @param content - The file content to parse.
+ * @param filepath - The file path (used for language detection).
+ * @returns Array of BreakPoint objects suitable for merging with regex break points.
+ */
+export declare function getASTBreakPoints(content: string, filepath: string): Promise<BreakPoint[]>;
+/**
+ * Check which tree-sitter grammars are available.
+ * Returns a status object for each supported language.
+ */
+export declare function getASTStatus(): Promise<{
+    available: boolean;
+    languages: {
+        language: SupportedLanguage;
+        available: boolean;
+        error?: string;
+    }[];
+}>;
+/**
+ * Metadata about a code symbol within a chunk.
+ * Stubbed for Phase 2 — always returns empty array in Phase 1.
+ */
+export interface SymbolInfo {
+    name: string;
+    kind: string;
+    signature?: string;
+    line: number;
+}
+/**
+ * Extract symbol metadata for code within a byte range.
+ * Stubbed for Phase 2 — returns empty array.
+ */
+export declare function extractSymbols(_content: string, _language: string, _startPos: number, _endPos: number): SymbolInfo[];

package/dist/ast.js

@@ -0,0 +1,51 @@
+var E=Object.defineProperty;var n=(t,e)=>E(t,"name",{value:e,configurable:!0});import{createRequire as S}from"node:module";import{extname as j}from"node:path";const P={".ts":"typescript",".tsx":"tsx",".js":"javascript",".jsx":"tsx",".mts":"typescript",".cts":"typescript",".mjs":"javascript",".cjs":"javascript",".py":"python",".go":"go",".rs":"rust"};function q(t){const e=j(t).toLowerCase();return P[e]??null}n(q,"detectLanguage");const i={typescript:{pkg:"tree-sitter-typescript",wasm:"tree-sitter-typescript.wasm",version:"0.23.2"},tsx:{pkg:"tree-sitter-typescript",wasm:"tree-sitter-tsx.wasm",version:"0.23.2"},javascript:{pkg:"tree-sitter-typescript",wasm:"tree-sitter-typescript.wasm",version:"0.23.2"},python:{pkg:"tree-sitter-python",wasm:"tree-sitter-python.wasm",version:"0.25.0"},go:{pkg:"tree-sitter-go",wasm:"tree-sitter-go.wasm",version:"0.25.0"},rust:{pkg:"tree-sitter-rust",wasm:"tree-sitter-rust.wasm",version:"0.24.0"}};function L(t,e){const a=i[t],r=e instanceof Error?e.message:String(e);return`${a.pkg}/${a.wasm} failed to load (${r}); falling back to regex chunking. Repair a broken global install with: bun add ${a.pkg}@${a.version}`}n(L,"formatGrammarLoadError");const M={typescript:`
+    (export_statement) @export
+    (class_declaration) @class
+    (function_declaration) @func
+    (method_definition) @method
+    (interface_declaration) @iface
+    (type_alias_declaration) @type
+    (enum_declaration) @enum
+    (import_statement) @import
+    (lexical_declaration (variable_declarator value: (arrow_function))) @func
+    (lexical_declaration (variable_declarator value: (function_expression))) @func
+  `,tsx:`
+    (export_statement) @export
+    (class_declaration) @class
+    (function_declaration) @func
+    (method_definition) @method
+    (interface_declaration) @iface
+    (type_alias_declaration) @type
+    (enum_declaration) @enum
+    (import_statement) @import
+    (lexical_declaration (variable_declarator value: (arrow_function))) @func
+    (lexical_declaration (variable_declarator value: (function_expression))) @func
+  `,javascript:`
+    (export_statement) @export
+    (class_declaration) @class
+    (function_declaration) @func
+    (method_definition) @method
+    (import_statement) @import
+    (lexical_declaration (variable_declarator value: (arrow_function))) @func
+    (lexical_declaration (variable_declarator value: (function_expression))) @func
+  `,python:`
+    (class_definition) @class
+    (function_definition) @func
+    (decorated_definition) @decorated
+    (import_statement) @import
+    (import_from_statement) @import
+  `,go:`
+    (type_declaration) @type
+    (function_declaration) @func
+    (method_declaration) @method
+    (import_declaration) @import
+  `,rust:`
+    (struct_item) @struct
+    (impl_item) @impl
+    (function_item) @func
+    (trait_item) @trait
+    (enum_item) @enum
+    (use_declaration) @import
+    (type_item) @type
+    (mod_item) @mod
+  `},C={class:100,iface:100,struct:100,trait:100,impl:100,mod:100,export:90,func:90,method:90,decorated:90,type:80,enum:80,import:60};let p=null,y=null,w=null,d=null;const v=new Set,x=new Map,l=new Map,f=new Map;async function h(){return d||(d=(async()=>{const t=await import("web-tree-sitter");p=t.Parser,y=t.Language,w=t.Query,await p.init()})()),d}n(h,"ensureInit");function G(t){const{pkg:e,wasm:a}=i[t];return S(import.meta.url).resolve(`${e}/${a}`)}n(G,"resolveGrammarPath");async function b(t){if(v.has(t))return null;const e=i[t].wasm;l.has(e)||l.set(e,(async()=>{const a=G(t);return y.load(a)})());try{return await l.get(e)}catch(a){v.add(t),l.delete(e);const r=L(t,a);return x.set(t,r),console.warn(`[qmd] AST grammar unavailable for ${t}: ${r}`),null}}n(b,"loadGrammar");function k(t,e){if(!f.has(t)){const a=M[t],r=new w(e,a);f.set(t,r)}return f.get(t)}n(k,"getQuery");async function O(t,e){const a=q(e);if(!a)return[];try{await h();const r=await b(a);if(!r)return[];const c=new p;c.setLanguage(r);const m=c.parse(t);if(!m)return c.delete(),[];const $=k(a,r).captures(m.rootNode),u=new Map;for(const s of $){const o=s.node.startIndex,_=C[s.name]??20,A=`ast:${s.name}`,g=u.get(o);(!g||_>g.score)&&u.set(o,{pos:o,score:_,type:A})}return m.delete(),c.delete(),Array.from(u.values()).sort((s,o)=>s.pos-o.pos)}catch(r){return console.warn(`[qmd] AST parse failed for ${e}, falling back to regex: ${r instanceof Error?r.message:r}`),[]}}n(O,"getASTBreakPoints");async function Q(){const t=[];try{await h()}catch(e){return{available:!1,languages:Object.keys(i).map(a=>({language:a,available:!1,error:`web-tree-sitter init failed: ${e instanceof Error?e.message:e}`}))}}for(const e of Object.keys(i))try{const a=await b(e);a?(k(e,a),t.push({language:e,available:!0})):t.push({language:e,available:!1,error:x.get(e)??"grammar failed to load"})}catch(a){t.push({language:e,available:!1,error:a instanceof Error?a.message:String(a)})}return{available:t.some(e=>e.available),languages:t}}n(Q,"getASTStatus");function U(t,e,a,r){return[]}n(U,"extractSymbols");export{q as detectLanguage,U as extractSymbols,L as formatGrammarLoadError,O as getASTBreakPoints,Q as getASTStatus};

package/dist/bench/bench.d.ts

@@ -0,0 +1,41 @@
+/**
+ * QMD Benchmark Harness
+ *
+ * Runs queries from a fixture file against multiple search backends
+ * and measures precision@k, recall, MRR, F1, and latency.
+ *
+ * Usage:
+ *   qmd bench <fixture.json> [--json] [--collection <name>]
+ *
+ * Backends tested:
+ *   - bm25: BM25 keyword search (searchLex)
+ *   - vector: Vector similarity search (searchVector)
+ *   - hybrid: BM25 + vector RRF fusion without reranking
+ *   - full: Full hybrid pipeline with LLM reranking
+ */
+import type { BackendSummaryByType, HardSummary, QueryResult, BenchmarkResult } from "./types.js";
+/** Per-type summary built from the existing computeSummary on each type's slice of results.
+ *  A type with zero queries gets no entry — pooling must skip it, never divide by zero. */
+export declare const computeSummaryByType: (results: QueryResult[]) => BackendSummaryByType;
+/** Count-weighted pool of the hard query types over the per-type summary — the numbers behind
+ *  the `RESULT-HARD` line bench-ko.sh prints and dogfood.sh gates. Nulls when empty. */
+export declare const computeHardSummary: (byType: BackendSummaryByType) => HardSummary;
+export type BenchCollectionInfo = {
+    name: string;
+    active_count: number;
+};
+/**
+ * Fail fast when the fixture's collection is missing or empty so `qmd bench`
+ * does not spend minutes printing a wall of 0.00 (#716).
+ */
+export declare function assertBenchCollectionReady(collections: BenchCollectionInfo[], collection?: string): void;
+export declare function benchSummaryAllZero(summary: BenchmarkResult["summary"]): boolean;
+export declare function allZeroBenchWarning(collection?: string): string;
+export declare function runBenchmark(fixturePath: string, options?: {
+    json?: boolean;
+    collection?: string;
+    backends?: string[];
+    dbPath?: string;
+    configPath?: string;
+    config?: import("../collections.js").CollectionConfig;
+}): Promise<BenchmarkResult>;

package/dist/bench/bench.js

@@ -0,0 +1,12 @@
+var v=Object.defineProperty;var i=(a,e)=>v(a,"name",{value:e,configurable:!0});import{readFileSync as x}from"node:fs";import{resolve as k}from"node:path";import{createStore as R,getDefaultDbPath as q}from"../index.js";import{scoreResults as S}from"./score.js";import{HARD_QUERY_TYPES as w}from"./types.js";function y(a){const e=a.split(`
+`).map((s,o)=>({trimmed:s.trim(),number:o+1})).filter(s=>s.trimmed.length>0);if(e.length===0)return;const t=/^(lex|vec|hyde):\s*/i,n=/^intent:\s*/i,r=[];let c;for(const s of e){if(n.test(s.trimmed)){if(c!==void 0)throw new Error(`Line ${s.number}: only one intent: line is allowed per benchmark query.`);if(c=s.trimmed.replace(n,"").trim(),!c)throw new Error(`Line ${s.number}: intent: must include text.`);continue}const o=s.trimmed.match(t);if(o){const f=o[1].toLowerCase(),m=s.trimmed.slice(o[0].length).trim();if(!m)throw new Error(`Line ${s.number} (${f}:) must include text.`);r.push({type:f,query:m,line:s.number});continue}if(e.length===1)return;throw new Error(`Line ${s.number} is missing a lex:/vec:/hyde:/intent: prefix.`)}if(c&&r.length===0)throw new Error("intent: cannot appear alone. Add at least one lex:, vec:, or hyde: line.");return r.length>0?{searches:r,intent:c}:void 0}i(y,"parseStructuredQuery");function b(a,e){const t=new Set,n=[];for(const r of a)if(!t.has(r)&&(t.add(r),n.push(r),n.length>=e))break;return n}i(b,"uniqueFiles");const g=[{name:"bm25",run:i(async(a,e,t,n)=>{const r=y(e.query),c=r?.searches.filter(o=>o.type==="lex");if(r){const o=[];for(const f of c??[]){const m=await a.searchLex(f.query,{limit:t,collection:n});o.push(...m.map(_=>_.filepath))}return b(o,t)}return(await a.searchLex(e.query,{limit:t,collection:n})).map(o=>o.filepath)},"run")},{name:"vector",run:i(async(a,e,t,n)=>{const r=y(e.query),c=r?.searches.filter(o=>o.type==="vec"||o.type==="hyde");if(r){const o=[];for(const f of c??[]){const m=await a.searchVector(f.query,{limit:t,collection:n});o.push(...m.map(_=>_.filepath))}return b(o,t)}return(await a.searchVector(e.query,{limit:t,collection:n})).map(o=>o.filepath)},"run")},{name:"hybrid",run:i(async(a,e,t,n)=>{const r=y(e.query);return(r?await a.search({queries:r.searches,intent:r.intent,limit:t,collection:n,rerank:!1}):await a.search({query:e.query,limit:t,collection:n,rerank:!1})).map(s=>s.file)},"run")},{name:"full",run:i(async(a,e,t,n)=>{const r=y(e.query);return(r?await a.search({queries:r.searches,intent:r.intent,limit:t,collection:n,rerank:!0}):await a.search({query:e.query,limit:t,collection:n,rerank:!0})).map(s=>s.file)},"run")}];async function E(a,e,t,n){const r=t.expected_in_top_k??t.expected_files.length,c=Math.max(Number.isFinite(r)?r:0,10),s=Date.now();let o;try{o=await e.run(a,t,c,n)}catch{return{precision_at_k:0,recall:0,recall_at_1:0,recall_at_3:0,recall_at_5:0,mrr:0,f1:0,hits_at_k:0,total_expected:t.expected_files.length,latency_ms:Date.now()-s,top_files:[],matched_files:[],unmatched_expected_files:t.expected_files}}const f=Date.now()-s;return{...S(o,t.expected_files,r),total_expected:t.expected_files.length,latency_ms:f,top_files:o.slice(0,10)}}i(E,"runQuery");function j(a){const e=[],t=i((r,c)=>r.slice(0,c).padEnd(c),"pad"),n=i(r=>r.toFixed(2).padStart(5),"num");e.push(`${t("Query",25)} ${t("Backend",8)} ${t("P@k",6)} ${t("R@1",6)} ${t("R@3",6)} ${t("R@5",6)} ${t("MRR",6)} ${t("F1",6)} ${t("ms",8)}`),e.push("-".repeat(88));for(const r of a){for(const[c,s]of Object.entries(r.backends))e.push(`${t(r.id,25)} ${t(c,8)} ${n(s.precision_at_k)} ${n(s.recall_at_1)} ${n(s.recall_at_3)} ${n(s.recall_at_5)} ${n(s.mrr)} ${n(s.f1)} ${String(Math.round(s.latency_ms)).padStart(7)}ms`);e.push("")}return e.join(`
+`)}i(j,"formatTable");function $(a){const e={},t=new Set;for(const n of a)for(const r of Object.keys(n.backends))t.add(r);for(const n of Array.from(t)){let r=0,c=0,s=0,o=0,f=0,m=0,_=0,p=0,u=0;for(const d of a){const l=d.backends[n];l&&(r+=l.precision_at_k,c+=l.recall,s+=l.recall_at_1,o+=l.recall_at_3,f+=l.recall_at_5,m+=l.mrr,_+=l.f1,p+=l.latency_ms,u++)}u>0&&(e[n]={avg_precision:r/u,avg_recall:c/u,avg_recall_at_1:s/u,avg_recall_at_3:o/u,avg_recall_at_5:f/u,avg_mrr:m/u,avg_f1:_/u,avg_latency_ms:p/u})}return e}i($,"computeSummary");const A=i(a=>{const e={},t=Array.from(new Set(a.map(n=>n.type))).sort();for(const n of t){const r=a.filter(c=>c.type===n);e[n]={};for(const[c,s]of Object.entries($(r)))e[n][c]={...s,count:r.length}}return e},"computeSummaryByType"),F=i(a=>{const e=[["hybrid_r1","hybrid","avg_recall_at_1"],["hybrid_mrr","hybrid","avg_mrr"],["full_r1","full","avg_recall_at_1"],["full_mrr","full","avg_mrr"]],t={hybrid_r1:null,hybrid_mrr:null,full_r1:null,full_mrr:null,n:0};for(const n of w)t.n+=Object.values(a[n]??{})[0]?.count??0;for(const[n,r,c]of e){let s=0,o=0;for(const f of w){const m=a[f]?.[r];m&&(s+=m[c]*m.count,o+=m.count)}t[n]=o>0?s/o:null}return t},"computeHardSummary");function O(a,e){if(e){const n=a.find(r=>r.name===e);if(!n){const r=a.map(s=>s.name),c=r.length>0?`Available: ${r.join(", ")}. Run 'qmd ls' to inspect.`:"Run 'qmd ls' to see available collections.";throw new Error(`Collection not found: ${e}
+${c}`)}if(n.active_count===0)throw new Error(`Collection '${e}' has no indexed documents.
+Run 'qmd update', then 'qmd ls ${e}' to confirm files are indexed before bench.`);return}const t=a.reduce((n,r)=>n+r.active_count,0);if(a.length===0||t===0)throw new Error(`No indexed documents found.
+Index a collection with 'qmd collection add' / 'qmd update' before running bench.`)}i(O,"assertBenchCollectionReady");function B(a){const e=Object.values(a);return e.length===0?!1:e.every(t=>t.avg_precision===0&&t.avg_recall===0&&t.avg_mrr===0)}i(B,"benchSummaryAllZero");function C(a){return`All benchmark scores were 0.00 \u2014 the collection is likely unindexed or the fixture's expected files are missing. Check with '${a?`qmd ls ${a}`:"qmd ls"}'.`}i(C,"allZeroBenchWarning");async function N(a,e={}){const t=x(k(a),"utf-8"),n=JSON.parse(t);if(!n.queries||!Array.isArray(n.queries))throw new Error("Invalid fixture: missing 'queries' array");if(n.queries.length===0)throw new Error(`Invalid fixture: '${a}' has no queries \u2014 nothing to run.
+Add at least one query; an empty fixture would otherwise report success with no results.`);const r=e.backends?g.filter(u=>e.backends.includes(u.name)):g;if(r.length===0){const u=(e.backends??[]).join(", ")||"(empty backend list)";throw new Error(`Unknown backend(s): ${u}.
+Available: ${g.map(d=>d.name).join(", ")}.`)}const c=await R({dbPath:e.dbPath??q(),...e.configPath?{configPath:e.configPath}:{},...e.config?{config:e.config}:{}}),s=e.collection??n.collection,o=[];try{const u=await c.listCollections();O(u,s);for(const d of n.queries){const l={};for(const h of r)e.json||process.stderr.write(`  ${d.id} / ${h.name}...`),l[h.name]=await E(c,h,d,s),e.json||process.stderr.write(` ${Math.round(l[h.name].latency_ms)}ms
+`);o.push({id:d.id,query:d.query,type:d.type,backends:l})}}finally{await c.close()}const f=$(o),m=new Date().toISOString().replace(/[:.]/g,"").slice(0,15),_=A(o),p={timestamp:m,fixture:a,results:o,summary:f,summary_by_type:_,summary_hard:F(_)};if(B(f)&&process.stderr.write(`
+${C(s)}
+`),e.json)console.log(JSON.stringify(p,null,2));else{console.log(`
+`+j(o)),console.log("Summary:"),console.log("-".repeat(70));const u=i((l,h)=>l.slice(0,h).padEnd(h),"pad"),d=i(l=>l.toFixed(3).padStart(6),"num");for(const[l,h]of Object.entries(f))console.log(`  ${u(l,8)} P@k=${d(h.avg_precision)} R@1=${d(h.avg_recall_at_1)} R@3=${d(h.avg_recall_at_3)} R@5=${d(h.avg_recall_at_5)} MRR=${d(h.avg_mrr)} F1=${d(h.avg_f1)} Avg=${Math.round(h.avg_latency_ms)}ms`)}return p}i(N,"runBenchmark");export{C as allZeroBenchWarning,O as assertBenchCollectionReady,B as benchSummaryAllZero,F as computeHardSummary,A as computeSummaryByType,N as runBenchmark};

package/dist/bench/score.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Scoring functions for the QMD benchmark harness.
+ *
+ * Computes precision@k, recall, MRR, and F1 for search results
+ * against ground-truth expected files.
+ */
+/**
+ * Normalize a file path for comparison.
+ * Strips qmd:// prefix, lowercases, removes leading/trailing slashes.
+ */
+export declare function normalizePath(p: string): string;
+/**
+ * Check if two paths refer to the same file.
+ * Handles different path formats by comparing normalized suffixes.
+ */
+export declare function pathsMatch(result: string, expected: string): boolean;
+type ScoreMetrics = {
+    precision_at_k: number;
+    recall: number;
+    recall_at_1: number;
+    recall_at_3: number;
+    recall_at_5: number;
+    mrr: number;
+    f1: number;
+    hits_at_k: number;
+    matched_files: string[];
+    unmatched_expected_files: string[];
+};
+/**
+ * Score a set of search results against expected files.
+ */
+export declare function scoreResults(resultFiles: string[], expectedFiles: string[], topK: number): ScoreMetrics;
+export {};

package/dist/bench/score.js

@@ -0,0 +1 @@
+var M=Object.defineProperty;var a=(n,t)=>M(n,"name",{value:t,configurable:!0});function e(n){if(n.startsWith("qmd://")){const t=n.slice(6),o=t.indexOf("/");n=o>=0?t.slice(o+1):t}return n.toLowerCase().replace(/^\/+|\/+$/g,"")}a(e,"normalizePath");function _(n,t){const o=e(n),h=e(t);return!!(o===h||o.endsWith("/"+h)||h.endsWith("/"+o))}a(_,"pathsMatch");function g(n,t,o){const h=n.slice(0,o);let c=0;for(const s of t)h.some(f=>_(f,s))&&c++;return c}a(g,"hitsWithin");function b(n,t,o){const h=g(n,t,o),c=[],s=[];for(const r of t)n.some(u=>_(u,r))?c.push(r):s.push(r);let f=0;for(let r=0;r<n.length;r++)if(t.some(u=>_(n[r],u))){f=1/(r+1);break}const l=Math.min(o,t.length),i=l>0?h/l:0,m=t.length>0?c.length/t.length:0,W=t.length>0?g(n,t,1)/t.length:0,k=t.length>0?g(n,t,3)/t.length:0,q=t.length>0?g(n,t,5)/t.length:0,w=i+m>0?2*(i*m)/(i+m):0;return{precision_at_k:i,recall:m,recall_at_1:W,recall_at_3:k,recall_at_5:q,mrr:f,f1:w,hits_at_k:h,matched_files:c,unmatched_expected_files:s}}a(b,"scoreResults");export{e as normalizePath,_ as pathsMatch,b as scoreResults};

package/dist/bench/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Types for the QMD benchmark harness.
+ *
+ * A benchmark fixture defines queries with expected results.
+ * The harness runs each query through multiple search backends
+ * and measures precision, recall, MRR, and latency.
+ */
+export type BenchmarkQueryType = "exact" | "semantic" | "topical" | "cross-domain" | "alias" | "sem-hard" | "multi" | "neg";
+/** Query types pooled into the hard `RESULT-HARD` gate line (bench-ko.sh / dogfood.sh). */
+export declare const HARD_QUERY_TYPES: readonly BenchmarkQueryType[];
+export interface BenchmarkQuery {
+    /** Unique identifier for the query */
+    id: string;
+    /** The search query text */
+    query: string;
+    /** Query difficulty/type for grouping results */
+    type: BenchmarkQueryType;
+    /** Human-readable description of what this tests */
+    description: string;
+    /** File paths (relative to collection) that should appear in results */
+    expected_files: string[];
+    /** How many of expected_files should appear in top-k results */
+    expected_in_top_k?: number;
+    /** For `neg` queries: the named-but-excluded concept's path (fixture-test invariant only) */
+    excluded?: string;
+}
+export interface BenchmarkFixture {
+    /** Description of the benchmark */
+    description: string;
+    /** Fixture format version */
+    version: number;
+    /** Optional collection to search within */
+    collection?: string;
+    /** The test queries */
+    queries: BenchmarkQuery[];
+}
+export interface BackendResult {
+    /** Fraction of top-k results that are relevant */
+    precision_at_k: number;
+    /** Fraction of expected files found anywhere in results */
+    recall: number;
+    /** Fraction of expected files found in the first result */
+    recall_at_1: number;
+    /** Fraction of expected files found in the top 3 results */
+    recall_at_3: number;
+    /** Fraction of expected files found in the top 5 results */
+    recall_at_5: number;
+    /** Reciprocal rank of first relevant result (1/rank, 0 if not found) */
+    mrr: number;
+    /** Harmonic mean of precision_at_k and recall */
+    f1: number;
+    /** Number of expected files found in top-k */
+    hits_at_k: number;
+    /** Total expected files */
+    total_expected: number;
+    /** Wall-clock latency in milliseconds */
+    latency_ms: number;
+    /** Top result file paths (for inspection) */
+    top_files: string[];
+    /** Expected files that were found anywhere in the returned result set */
+    matched_files: string[];
+    /** Expected files missing from the returned result set */
+    unmatched_expected_files: string[];
+}
+export interface QueryResult {
+    id: string;
+    query: string;
+    type: string;
+    backends: Record<string, BackendResult>;
+}
+/** Per-backend averages over a group of queries (the shape of summary[backend]). */
+export interface BackendSummary {
+    avg_precision: number;
+    avg_recall: number;
+    avg_recall_at_1: number;
+    avg_recall_at_3: number;
+    avg_recall_at_5: number;
+    avg_mrr: number;
+    avg_f1: number;
+    avg_latency_ms: number;
+}
+/** Per-backend averages over one query type; count = queries of that type (the same for every backend). */
+export type BackendSummaryByType = Record<string, Record<string, BackendSummary & {
+    count: number;
+}>>;
+/** Count-weighted pool over the hard query types; nulls when no hard queries ran (printed as nan). */
+export interface HardSummary {
+    hybrid_r1: number | null;
+    hybrid_mrr: number | null;
+    full_r1: number | null;
+    full_mrr: number | null;
+    n: number;
+}
+export interface BenchmarkResult {
+    timestamp: string;
+    fixture: string;
+    results: QueryResult[];
+    summary: Record<string, BackendSummary>;
+    summary_by_type: BackendSummaryByType;
+    summary_hard: HardSummary;
+}

package/dist/bench/types.js

@@ -0,0 +1 @@
+const e=["sem-hard","multi","neg"];export{e as HARD_QUERY_TYPES};

package/dist/cli/build-info.json

@@ -0,0 +1,4 @@
+{
+  "commit": "0f8df3f",
+  "builtAt": "2026-10-15T04:39:30.671Z"
+}

package/dist/cli/embed-lock.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Process-level exclusive lock for `qmd embed`.
+ *
+ * Concurrent embed runs against the same index can race on vectors_vec
+ * (UNIQUE constraint on hash_seq). This lockfile keeps a second process from
+ * starting while another embed holds the lock. Stale files left by crashed
+ * processes are recovered via PID identity checks (same spirit as mcp-pid.ts).
+ */
+export type EmbedLockHandle = {
+    lockPath: string;
+    release: () => void;
+};
+/** Lockfile path sibling to the index database. */
+export declare function embedLockPathForDb(dbPath: string): string;
+/** True if `pid` still owns a live embed/qmd process (or is this process). */
+export declare function isLiveEmbedLockHolder(pid: number): boolean;
+/**
+ * Try to acquire an exclusive embed lock at `lockPath`.
+ * Returns a handle with `release()` on success, or `null` if another live
+ * qmd process already holds the lock.
+ */
+export declare function tryAcquireEmbedLock(lockPath: string): EmbedLockHandle | null;
+/** User-facing message when a second embed is skipped. */
+export declare const EMBED_LOCK_BUSY_MESSAGE = "Another embed process is already running. Skipping.";

package/dist/cli/embed-lock.js

@@ -0,0 +1,2 @@
+var d=Object.defineProperty;var t=(e,r)=>d(e,"name",{value:r,configurable:!0});import{existsSync as l,readFileSync as f,unlinkSync as u,writeFileSync as m}from"node:fs";import{dirname as p,join as a}from"node:path";import{isQmdMcpPid as y}from"./mcp-pid.js";function g(e){return a(p(e),".qmd-embed.lock")}t(g,"embedLockPathForDb");function o(e){try{const r=f(e,"utf-8").trim(),n=parseInt(r,10);return!Number.isInteger(n)||n<=0?null:n}catch{return null}}t(o,"readLockPid");function s(e){return!Number.isInteger(e)||e<=0?!1:e===process.pid?!0:y(e)}t(s,"isLiveEmbedLockHolder");function b(e){m(e,`${process.pid}
+`,{flag:"wx"});let r=!1;return{lockPath:e,release:t(()=>{if(!r){r=!0;try{if(!l(e))return;o(e)===process.pid&&u(e)}catch{}}},"release")}}t(b,"createOwnedLock");function I(e){for(let n=0;n<2;n++)try{return b(e)}catch(i){if((typeof i=="object"&&i!==null&&"code"in i?i.code:void 0)!=="EEXIST")throw i;const c=o(e);if(c!==null&&s(c))return null;try{u(e)}catch{}}const r=o(e);return r!==null&&s(r),null}t(I,"tryAcquireEmbedLock");const A="Another embed process is already running. Skipping.";export{A as EMBED_LOCK_BUSY_MESSAGE,g as embedLockPathForDb,s as isLiveEmbedLockHolder,I as tryAcquireEmbedLock};