@wei840222/qmd 2026.8.23

package/dist/bench/score.js

@@ -0,0 +1,107 @@
+/**
+ * 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 function normalizePath(p) {
+    if (p.startsWith("qmd://")) {
+        // qmd://collection/docs/readme.md → docs/readme.md
+        const withoutScheme = p.slice("qmd://".length);
+        const slashIdx = withoutScheme.indexOf("/");
+        p = slashIdx >= 0 ? withoutScheme.slice(slashIdx + 1) : withoutScheme;
+    }
+    return p.toLowerCase().replace(/^\/+|\/+$/g, "");
+}
+/**
+ * Check if two paths refer to the same file.
+ * Handles different path formats by comparing normalized suffixes.
+ */
+export function pathsMatch(result, expected) {
+    const nr = normalizePath(result);
+    const ne = normalizePath(expected);
+    if (nr === ne)
+        return true;
+    if (nr.endsWith(`/${ne}`) || ne.endsWith(`/${nr}`))
+        return true;
+    return false;
+}
+export function percentile(values, quantile) {
+    if (!Number.isFinite(quantile) || quantile <= 0 || quantile > 1) {
+        throw new RangeError("quantile must be greater than 0 and at most 1");
+    }
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.ceil(quantile * sorted.length) - 1];
+}
+function hitsWithin(resultFiles, expectedFiles, k) {
+    const topKResults = resultFiles.slice(0, k);
+    let hits = 0;
+    for (const expected of expectedFiles) {
+        if (topKResults.some(r => pathsMatch(r, expected))) {
+            hits++;
+        }
+    }
+    return hits;
+}
+/**
+ * Score a set of search results against expected files.
+ */
+export function scoreResults(resultFiles, expectedFiles, topK, mustNotMatchFiles = []) {
+    // Count hits in top-k
+    const hitsAtK = hitsWithin(resultFiles, expectedFiles, topK);
+    const matchedFiles = [];
+    const unmatchedExpectedFiles = [];
+    for (const expected of expectedFiles) {
+        if (resultFiles.some(r => pathsMatch(r, expected))) {
+            matchedFiles.push(expected);
+        }
+        else {
+            unmatchedExpectedFiles.push(expected);
+        }
+    }
+    // MRR: reciprocal rank of first relevant result
+    let mrr = 0;
+    let mrrAt10 = 0;
+    for (let i = 0; i < resultFiles.length; i++) {
+        if (expectedFiles.some(e => pathsMatch(resultFiles[i], e))) {
+            mrr = 1 / (i + 1);
+            if (i < 10)
+                mrrAt10 = mrr;
+            break;
+        }
+    }
+    const top10Results = resultFiles.slice(0, 10);
+    const falsePositiveFiles = mustNotMatchFiles.filter(expected => top10Results.some(result => pathsMatch(result, expected)));
+    const denominator = Math.min(topK, expectedFiles.length);
+    const precision_at_k = denominator > 0 ? hitsAtK / denominator : 0;
+    const recall = expectedFiles.length > 0 ? matchedFiles.length / expectedFiles.length : 0;
+    const recall_at_1 = expectedFiles.length > 0 ? hitsWithin(resultFiles, expectedFiles, 1) / expectedFiles.length : 0;
+    const recall_at_3 = expectedFiles.length > 0 ? hitsWithin(resultFiles, expectedFiles, 3) / expectedFiles.length : 0;
+    const recall_at_5 = expectedFiles.length > 0 ? hitsWithin(resultFiles, expectedFiles, 5) / expectedFiles.length : 0;
+    const recall_at_10 = expectedFiles.length > 0 ? hitsWithin(resultFiles, expectedFiles, 10) / expectedFiles.length : 0;
+    const f1 = precision_at_k + recall > 0
+        ? 2 * (precision_at_k * recall) / (precision_at_k + recall)
+        : 0;
+    return {
+        precision_at_k,
+        recall,
+        recall_at_1,
+        recall_at_3,
+        recall_at_5,
+        recall_at_10,
+        mrr,
+        mrr_at_10: mrrAt10,
+        f1,
+        hits_at_k: hitsAtK,
+        false_positive_count: falsePositiveFiles.length,
+        false_positive_files: falsePositiveFiles,
+        matched_files: matchedFiles,
+        unmatched_expected_files: unmatchedExpectedFiles,
+    };
+}

package/dist/bench/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 interface BenchmarkQuery {
+    /** Unique identifier for the query */
+    id: string;
+    /** The search query text */
+    query: string;
+    /** Query difficulty/type for grouping results */
+    type: "exact" | "semantic" | "topical" | "cross-domain" | "alias";
+    /** Human-readable description of what this tests */
+    description: string;
+    /** Legacy file paths (relative to collection) that should appear in results */
+    expected_files?: string[];
+    /** Stable document IDs that should appear in results */
+    relevant_doc_ids?: string[];
+    /** Stable document IDs that must not appear in the top 10 results */
+    must_not_match_doc_ids?: string[];
+    /** Scenario labels used to group benchmark results */
+    scenario_tags?: string[];
+    /** How many of expected_files should appear in top-k results */
+    expected_in_top_k: number;
+}
+export interface BenchmarkDocument {
+    /** Stable identifier used by query relevance judgements */
+    id: string;
+    /** File path relative to the benchmark collection */
+    file: string;
+}
+export interface BenchmarkFixture {
+    /** Description of the benchmark */
+    description: string;
+    /** Fixture format version */
+    version: number;
+    /** Optional collection to search within */
+    collection?: string;
+    /** Stable document catalogue for version 2 relevance judgements */
+    documents?: BenchmarkDocument[];
+    /** The test queries */
+    queries: BenchmarkQuery[];
+}
+export interface ResolvedBenchmarkQuery extends Omit<BenchmarkQuery, "expected_files"> {
+    expected_files: string[];
+    must_not_match_files: string[];
+}
+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;
+    /** Fraction of expected files found in the top 10 results */
+    recall_at_10: number;
+    /** Reciprocal rank of first relevant result (1/rank, 0 if not found) */
+    mrr: number;
+    /** Reciprocal rank of first relevant result within the top 10 */
+    mrr_at_10: number;
+    /** Harmonic mean of precision_at_k and recall */
+    f1: number;
+    /** Number of expected files found in top-k */
+    hits_at_k: number;
+    /** Number of prohibited files found in the top 10 */
+    false_positive_count: number;
+    /** Prohibited files found in the top 10 */
+    false_positive_files: string[];
+    /** 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;
+    scenario_tags?: string[];
+    backends: Record<string, BackendResult>;
+}
+export interface BenchmarkResult {
+    timestamp: string;
+    fixture: string;
+    results: QueryResult[];
+    summary: Record<string, {
+        avg_precision: number;
+        avg_recall: number;
+        avg_recall_at_1: number;
+        avg_recall_at_3: number;
+        avg_recall_at_5: number;
+        avg_recall_at_10: number;
+        avg_mrr: number;
+        avg_mrr_at_10: number;
+        false_positive_count: number;
+        avg_f1: number;
+        avg_latency_ms: number;
+    }>;
+}

package/dist/bench/types.js

@@ -0,0 +1,8 @@
+/**
+ * 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 {};

package/dist/cli/build-info.json

@@ -0,0 +1,4 @@
+{
+  "commit": "f7e2cfc",
+  "builtAt": "2026-08-23T03:21:48.505Z"
+}

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,94 @@
+/**
+ * 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).
+ */
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isQmdMcpPid } from "./mcp-pid.js";
+/** Lockfile path sibling to the index database. */
+export function embedLockPathForDb(dbPath) {
+    return join(dirname(dbPath), ".qmd-embed.lock");
+}
+function readLockPid(lockPath) {
+    try {
+        const raw = readFileSync(lockPath, "utf-8").trim();
+        const pid = parseInt(raw, 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return null;
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if `pid` still owns a live embed/qmd process (or is this process). */
+export function isLiveEmbedLockHolder(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    // Same-process re-check: we obviously still hold our own lock.
+    if (pid === process.pid)
+        return true;
+    return isQmdMcpPid(pid);
+}
+function createOwnedLock(lockPath) {
+    writeFileSync(lockPath, `${process.pid}\n`, { flag: "wx" });
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            if (!existsSync(lockPath))
+                return;
+            const written = readLockPid(lockPath);
+            if (written === process.pid)
+                unlinkSync(lockPath);
+        }
+        catch {
+            // best-effort cleanup
+        }
+    };
+    return { lockPath, release };
+}
+/**
+ * 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 function tryAcquireEmbedLock(lockPath) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            return createOwnedLock(lockPath);
+        }
+        catch (err) {
+            const code = typeof err === "object" && err !== null && "code" in err
+                ? err.code
+                : undefined;
+            if (code !== "EEXIST")
+                throw err;
+            const holderPid = readLockPid(lockPath);
+            if (holderPid !== null && isLiveEmbedLockHolder(holderPid)) {
+                return null;
+            }
+            // Stale / unreadable / recycled PID — remove and retry once.
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                // Another process may have claimed it; loop and try wx again.
+            }
+        }
+    }
+    // Final attempt lost the race to a live holder (or repeated EEXIST).
+    const holderPid = readLockPid(lockPath);
+    if (holderPid !== null && isLiveEmbedLockHolder(holderPid)) {
+        return null;
+    }
+    return null;
+}
+/** User-facing message when a second embed is skipped. */
+export const EMBED_LOCK_BUSY_MESSAGE = "Another embed process is already running. Skipping.";

package/dist/cli/embedding-owner.d.ts

@@ -0,0 +1,10 @@
+import { LocalEmbeddingProviderOwner } from "../embedding/local.js";
+import type { EmbeddingProvider, EmbeddingProviderOwner } from "../embedding/provider.js";
+type LocalEmbeddingRuntime = ConstructorParameters<typeof LocalEmbeddingProviderOwner>[0];
+export interface CliEmbeddingProviderConfig {
+    provider: "local" | "openai";
+    model: string;
+    dimension: number | null;
+}
+export declare function createCliEmbeddingProviderOwner(config: CliEmbeddingProviderConfig, runtime: LocalEmbeddingRuntime, remoteProvider?: EmbeddingProvider): EmbeddingProviderOwner;
+export {};

package/dist/cli/embedding-owner.js

@@ -0,0 +1,20 @@
+import { LocalEmbeddingProviderOwner } from "../embedding/local.js";
+import { CompositeEmbeddingProviderOwner } from "../embedding/owner.js";
+import { waitForLLMSessionsToDrain } from "../llm.js";
+export function createCliEmbeddingProviderOwner(config, runtime, remoteProvider) {
+    if (config.provider === "local") {
+        return new LocalEmbeddingProviderOwner(runtime, {
+            model: config.model,
+            ...(config.dimension == null ? {} : { dimension: config.dimension }),
+        });
+    }
+    if (!remoteProvider?.remote) {
+        throw new Error("OpenAI CLI composition requires a remote embedding provider.");
+    }
+    return new CompositeEmbeddingProviderOwner(remoteProvider, {
+        dispose: async () => {
+            await waitForLLMSessionsToDrain(runtime);
+            await runtime.dispose();
+        },
+    });
+}

package/dist/cli/formatter.d.ts

@@ -0,0 +1,120 @@
+/**
+ * formatter.ts - Output formatting utilities for QMD
+ *
+ * Provides methods to format search results and documents into various output formats:
+ * JSON, CSV, XML, Markdown, files list, and CLI (colored terminal output).
+ */
+import type { SearchResult, MultiGetResult, DocumentResult } from "../store.js";
+export type { SearchResult, MultiGetResult, DocumentResult };
+export type MultiGetFile = {
+    filepath: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    context?: string | null;
+    skipped: false;
+} | {
+    filepath: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    context?: string | null;
+    skipped: true;
+    skipReason: string;
+};
+export type OutputFormat = "cli" | "csv" | "md" | "xml" | "files" | "json";
+export type FormatOptions = {
+    full?: boolean;
+    query?: string;
+    useColor?: boolean;
+    lineNumbers?: boolean;
+    intent?: string;
+};
+/**
+ * Add line numbers to text content.
+ * Each line becomes: "{lineNum}: {content}"
+ * @param text The text to add line numbers to
+ * @param startLine Optional starting line number (default: 1)
+ */
+export declare function addLineNumbers(text: string, startLine?: number): string;
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export declare function getDocid(hash: string): string;
+export declare function escapeCSV(value: string | null | number): string;
+export declare function escapeXml(str: string): string;
+/**
+ * Format search results as JSON
+ */
+export declare function searchResultsToJson(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as CSV
+ */
+export declare function searchResultsToCsv(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as simple files list (docid,score,filepath,context)
+ */
+export declare function searchResultsToFiles(results: SearchResult[]): string;
+/**
+ * Format search results as Markdown
+ */
+export declare function searchResultsToMarkdown(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as XML
+ */
+export declare function searchResultsToXml(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results for MCP (simpler CSV format with pre-extracted snippets)
+ */
+export declare function searchResultsToMcpCsv(results: {
+    docid: string;
+    file: string;
+    title: string;
+    score: number;
+    context: string | null;
+    snippet: string;
+}[]): string;
+/**
+ * Format documents as JSON
+ */
+export declare function documentsToJson(results: MultiGetFile[]): string;
+/**
+ * Format documents as CSV
+ */
+export declare function documentsToCsv(results: MultiGetFile[]): string;
+/**
+ * Format documents as files list
+ */
+export declare function documentsToFiles(results: MultiGetFile[]): string;
+/**
+ * Format documents as Markdown
+ */
+export declare function documentsToMarkdown(results: MultiGetFile[]): string;
+/**
+ * Format documents as XML
+ */
+export declare function documentsToXml(results: MultiGetFile[]): string;
+/**
+ * Format a single DocumentResult as JSON
+ */
+export declare function documentToJson(doc: DocumentResult): string;
+/**
+ * Format a single DocumentResult as Markdown
+ */
+export declare function documentToMarkdown(doc: DocumentResult): string;
+/**
+ * Format a single DocumentResult as XML
+ */
+export declare function documentToXml(doc: DocumentResult): string;
+/**
+ * Format a single document to the specified format
+ */
+export declare function formatDocument(doc: DocumentResult, format: OutputFormat): string;
+/**
+ * Format search results to the specified output format
+ */
+export declare function formatSearchResults(results: SearchResult[], format: OutputFormat, opts?: FormatOptions): string;
+/**
+ * Format documents to the specified output format
+ */
+export declare function formatDocuments(results: MultiGetFile[], format: OutputFormat): string;