@zvec/zvec-grep 0.1.0

package/dist/engine/service/zvec-grep.js

@@ -0,0 +1,935 @@
+import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, resolve } from "node:path";
+import { Collection, CollectionRegistry, } from "../collection/index.js";
+import { collectionDetail, detail, EngineError, errorDetails, } from "../errors/index.js";
+import { createEmbeddingModel, createEmbeddingModelFromReference, } from "../models/index.js";
+import { ANONYMOUS_COLLECTION_NAME, anonymousCollectionPath, anonymousHome, anonymousIndexLocation, findNearestAnonymousIndex, resolveZvecGrepRoot, } from "./root.js";
+import { runLexicalFallback, runRgSearch } from "./lexical.js";
+import { defaultHome } from "../utils/path.js";
+import { acquireReadWriteLock, assertNoWriteLock } from "../utils/lock.js";
+const DEFAULT_CONTEXT_LIMIT = 10;
+const DEFAULT_CONTEXT_TOTAL_LIMIT = 30;
+const DEFAULT_LOCAL_EMBEDDING = "local/embeddinggemma-300m";
+export async function createZvecGrep(options = {}) {
+    return new ZvecGrepService(options);
+}
+class ZvecGrepService {
+    options;
+    root;
+    collections;
+    embeddingModel;
+    embeddingModelExplicit;
+    recoveredEmbeddingModels = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.root = resolveZvecGrepRoot(options.root);
+        this.embeddingModelExplicit = hasExplicitEmbeddingModel(options);
+        this.embeddingModel = resolveEmbeddingModel(options, this.root);
+        this.collections = {
+            list: () => this.listCollections(),
+            info: (name) => this.collectionInfo(name),
+            status: (name) => this.collectionStatus(name),
+            index: (name, paths, indexOptions) => this.indexCollection(name, paths, indexOptions),
+            remove: (name) => this.removeCollection(name),
+        };
+    }
+    async init(options = {}) {
+        this.ensureOpen();
+        const root = resolveZvecGrepRoot(options.root ?? this.root);
+        const location = anonymousIndexLocation(root);
+        return await withHomeWriteLock(location.home, options.rebuild ? "init.rebuild" : "init", async () => {
+            const existing = readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME);
+            const embeddingModel = this.embeddingModelForIndex(existing, location.home, "init");
+            const registry = new CollectionRegistry(location.home, embeddingModel);
+            try {
+                const rootPaths = resolveIndexRootPaths(existing, options.rootPaths, root, {
+                    resetPaths: options.resetPaths === true,
+                    includePaths: options.includePaths,
+                    excludePaths: options.excludePaths,
+                });
+                if (options.rebuild) {
+                    registry.remove(ANONYMOUS_COLLECTION_NAME);
+                }
+                if (registry.has(ANONYMOUS_COLLECTION_NAME)) {
+                    assertCollectionEmbeddingMatchesCurrentModel(registry.get(ANONYMOUS_COLLECTION_NAME), embeddingModel, "zg --init --rebuild");
+                    registry.updateRootPaths(ANONYMOUS_COLLECTION_NAME, rootPaths);
+                }
+                else {
+                    registry.create(ANONYMOUS_COLLECTION_NAME, rootPaths, anonymousCollectionPath(root));
+                }
+                return await registry.open(ANONYMOUS_COLLECTION_NAME).index({
+                    rebuild: false,
+                    embeddingConcurrency: options.embeddingConcurrency,
+                    onProgress: options.onProgress,
+                });
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async context(options) {
+        this.ensureOpen();
+        const request = normalizeContextRequest(options);
+        if (options.collection) {
+            return this.contextFromNamedCollection(request, options);
+        }
+        const startRoot = resolveZvecGrepRoot(options.root ?? this.root);
+        if (options.rg) {
+            return this.contextFromRg(startRoot, request, options);
+        }
+        assertNearestAnonymousHomeUnlocked(startRoot, "context");
+        const location = findNearestAnonymousIndex(startRoot);
+        if (location) {
+            if (options.autoUpdate !== false) {
+                await this.refreshAnonymousIndexForContext(location, options);
+            }
+            return await withHomeReadLock(location.home, "context", () => this.contextFromAnonymousIndex(location, request, options));
+        }
+        throw anonymousIndexNotFoundError(startRoot);
+    }
+    async info(options = {}) {
+        this.ensureOpen();
+        const startRoot = resolveZvecGrepRoot(options.root ?? this.root);
+        assertNearestAnonymousHomeUnlocked(startRoot, "info");
+        const nearest = findNearestAnonymousIndex(startRoot);
+        if (!nearest) {
+            const location = anonymousIndexLocation(startRoot);
+            return {
+                root: startRoot,
+                initialized: false,
+                home: location.home,
+                indexPath: location.collectionPath,
+                source: "uninitialized",
+                suggestion: "zg --init",
+            };
+        }
+        return await withHomeReadLock(nearest.home, "info", async () => {
+            const registry = new CollectionRegistry(nearest.home, undefined, true);
+            try {
+                const collection = registry.get(ANONYMOUS_COLLECTION_NAME);
+                return {
+                    root: nearest.root,
+                    initialized: collection !== null,
+                    home: nearest.home,
+                    indexPath: nearest.collectionPath,
+                    source: collection ? "index" : "uninitialized",
+                    collection: collection ?? undefined,
+                    status: collection ? await registry.status(ANONYMOUS_COLLECTION_NAME) : null,
+                    suggestion: collection ? undefined : "zg --init",
+                };
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async close() {
+        const models = new Set([
+            ...(this.embeddingModel ? [this.embeddingModel] : []),
+            ...this.recoveredEmbeddingModels.values(),
+        ]);
+        this.recoveredEmbeddingModels.clear();
+        for (const model of models) {
+            await model.dispose();
+        }
+        this.closed = true;
+    }
+    async listCollections() {
+        this.ensureOpen();
+        return await withHomeReadLock(serviceHome(this.options), "collections.list", async () => {
+            const registry = this.createRegistry(true);
+            try {
+                return registry.list();
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async collectionInfo(name) {
+        this.ensureOpen();
+        return await withHomeReadLock(serviceHome(this.options), "collections.info", async () => {
+            const registry = this.createRegistry(true);
+            try {
+                return registry.get(name);
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async collectionStatus(name) {
+        this.ensureOpen();
+        return await withHomeReadLock(serviceHome(this.options), "collections.status", async () => {
+            const registry = this.createRegistry(true);
+            try {
+                return await registry.status(name);
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async indexCollection(name, paths, options = {}) {
+        this.ensureOpen();
+        const home = serviceHome(this.options);
+        return await withHomeWriteLock(home, options.rebuild ? "collections.index.rebuild" : "collections.index", async () => {
+            const existing = readCollectionInfo(home, name);
+            const embeddingModel = this.embeddingModelForIndex(existing, home, "collections.index");
+            const registry = this.createRegistry(false, embeddingModel);
+            try {
+                const requestedRootPaths = paths === undefined
+                    ? undefined
+                    : Array.isArray(paths)
+                        ? paths
+                        : [paths];
+                const rootPaths = resolveIndexRootPaths(existing, requestedRootPaths, this.root, {
+                    resetPaths: options.resetPaths === true,
+                    includePaths: options.includePaths,
+                    excludePaths: options.excludePaths,
+                });
+                if (options.rebuild) {
+                    registry.remove(name);
+                }
+                if (registry.has(name)) {
+                    assertCollectionEmbeddingMatchesCurrentModel(registry.get(name), embeddingModel, "zg --collections index <name> --rebuild");
+                    registry.updateRootPaths(name, rootPaths);
+                }
+                else {
+                    registry.create(name, rootPaths);
+                }
+                return await registry.open(name).index({
+                    embeddingConcurrency: options.embeddingConcurrency,
+                    onProgress: options.onProgress,
+                });
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async removeCollection(name) {
+        this.ensureOpen();
+        return await withHomeWriteLock(serviceHome(this.options), "collections.remove", async () => {
+            const registry = this.createRegistry(false);
+            try {
+                return registry.remove(name);
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async contextFromAnonymousIndex(location, request, options) {
+        const registry = new CollectionRegistry(location.home, undefined, true);
+        try {
+            const info = registry.get(ANONYMOUS_COLLECTION_NAME);
+            if (!info) {
+                throw new EngineError("Collection not found", {
+                    code: "ZVEC_GREP.ENGINE.COLLECTION.NOT_FOUND",
+                });
+            }
+            const collection = this.openCollectionForSearch(info, request, location.home);
+            try {
+                return await this.contextFromCollection({
+                    root: location.root,
+                    request,
+                    collection,
+                    anonymous: true,
+                    options,
+                });
+            }
+            finally {
+                collection.close();
+            }
+        }
+        finally {
+            registry.close();
+        }
+    }
+    async refreshAnonymousIndexForContext(location, options) {
+        const needsRefresh = await withHomeReadLock(location.home, "context.status", async () => {
+            const registry = new CollectionRegistry(location.home, undefined, true);
+            try {
+                const status = await registry.status(ANONYMOUS_COLLECTION_NAME);
+                return status ? collectionIndexStatusNeedsRefresh(status) : false;
+            }
+            finally {
+                registry.close();
+            }
+        });
+        if (!needsRefresh) {
+            return;
+        }
+        await withHomeWriteLock(location.home, "context.refresh", async () => {
+            const existing = readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME);
+            if (!existing) {
+                return;
+            }
+            const stillNeedsRefresh = await collectionNeedsRefresh(location.home, ANONYMOUS_COLLECTION_NAME);
+            if (!stillNeedsRefresh) {
+                return;
+            }
+            const embeddingModel = this.embeddingModelForIndex(existing, location.home, "context.refresh");
+            assertCollectionEmbeddingMatchesCurrentModel(existing, embeddingModel, "zg --init --rebuild");
+            const registry = new CollectionRegistry(location.home, embeddingModel);
+            try {
+                await registry.open(ANONYMOUS_COLLECTION_NAME).index({
+                    embeddingConcurrency: options.embeddingConcurrency,
+                    onProgress: options.onAutoUpdateProgress,
+                });
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async contextFromNamedCollection(request, options) {
+        const collectionName = options.collection;
+        return await withHomeReadLock(serviceHome(this.options), "collection.context", async () => {
+            const registry = this.createRegistry(true, undefined);
+            try {
+                const info = registry.get(collectionName);
+                if (!info) {
+                    throw new EngineError("Collection not found", {
+                        code: "ZVEC_GREP.ENGINE.COLLECTION.NOT_FOUND",
+                        context: errorDetails([collectionDetail(collectionName)]),
+                    });
+                }
+                const collection = this.openCollectionForSearch(info, request, registry.home);
+                const root = collection.info.rootPaths[0]?.absolutePath ?? resolveZvecGrepRoot(options.root ?? this.root);
+                try {
+                    return await this.contextFromCollection({
+                        root,
+                        request,
+                        collection,
+                        anonymous: false,
+                        options: {
+                            ...options,
+                            fallback: "disabled",
+                        },
+                    });
+                }
+                finally {
+                    collection.close();
+                }
+            }
+            finally {
+                registry.close();
+            }
+        });
+    }
+    async contextFromCollection(input) {
+        const searches = [];
+        const limit = contextGroupLimit(input.options.limit, input.request.groups.length);
+        for (const group of input.request.groups) {
+            searches.push(await input.collection.searchPlan({
+                routes: group.routes,
+                limit,
+                trace: input.options.trace,
+                preferSymbol: input.options.preferSymbol,
+                symbolTypes: input.options.symbolTypes,
+                includePaths: input.options.includePaths,
+                excludePaths: input.options.excludePaths,
+                modifiedAfter: input.options.modifiedAfter,
+                modifiedBefore: input.options.modifiedBefore,
+            }));
+        }
+        const items = dedupeAndRerankContextItems(searches.flatMap((search) => searchPlanToContextItems(search, input.root)));
+        return {
+            query: input.request.displayQuery,
+            root: input.root,
+            source: "index",
+            coverage: "ranked_sample",
+            collection: {
+                id: input.collection.info.id,
+                name: input.collection.info.name,
+                path: input.collection.info.path,
+                anonymous: input.anonymous,
+            },
+            items,
+            diagnostics: {
+                emptyReason: items.length === 0 ? "no_matches" : undefined,
+                index: {
+                    hitsReturned: items.length,
+                    routes: searches.flatMap((search) => search.plan.routes),
+                },
+            },
+        };
+    }
+    async contextFromLexicalFallback(root, request, options) {
+        const fallbackResults = [];
+        const limit = contextGroupLimit(options.limit, request.groups.length);
+        for (const query of request.fallbackQueries) {
+            fallbackResults.push(await runLexicalFallback({
+                root,
+                query,
+                limit,
+                includePaths: options.includePaths,
+                excludePaths: options.excludePaths,
+                modifiedAfter: options.modifiedAfter,
+                modifiedBefore: options.modifiedBefore,
+                rgOptions: options.rgOptions,
+            }));
+        }
+        const items = dedupeAndRerankContextItems(fallbackResults.flatMap((fallback) => fallback.items));
+        const diagnostics = mergeFallbackDiagnostics(fallbackResults);
+        return {
+            query: request.displayQuery,
+            root,
+            source: "lexical_fallback",
+            coverage: diagnostics.truncated ? "lexical_truncated" : "lexical_exhaustive",
+            items,
+            diagnostics: {
+                emptyReason: items.length === 0 ? "no_matches" : undefined,
+                fallback: diagnostics,
+            },
+        };
+    }
+    async contextFromRg(root, request, options) {
+        let rgResult;
+        try {
+            rgResult = await runRgSearch({
+                root,
+                patterns: request.fallbackQueries,
+                paths: options.rgPaths,
+                limit: options.limit,
+                includePaths: options.includePaths,
+                excludePaths: options.excludePaths,
+                modifiedAfter: options.modifiedAfter,
+                modifiedBefore: options.modifiedBefore,
+                rgOptions: options.rgOptions,
+            });
+        }
+        catch (cause) {
+            throw new EngineError("Search failed", {
+                code: "ZVEC_GREP.ENGINE.SEARCH.FAILED",
+                context: errorDetails([
+                    detail("source", "rg"),
+                    detail("root", root),
+                ]),
+                cause,
+            });
+        }
+        const items = dedupeAndRerankContextItems(rgResult.items);
+        const emptyReason = items.length === 0
+            ? rgEmptyReason(rgResult.diagnostics)
+            : undefined;
+        return {
+            query: request.displayQuery,
+            root,
+            source: "rg",
+            coverage: rgResult.diagnostics.truncated ? "lexical_truncated" : "lexical_exhaustive",
+            items,
+            diagnostics: {
+                emptyReason,
+                fallback: rgResult.diagnostics,
+            },
+        };
+    }
+    createRegistry(readOnly, embeddingModel = this.embeddingModel) {
+        return new CollectionRegistry(this.options.home, embeddingModel, readOnly);
+    }
+    openCollectionForSearch(info, request, registryHome) {
+        return new Collection(info, this.embeddingModelForSearch(info.embedding, request, registryHome), true);
+    }
+    embeddingModelForSearch(schema, request, registryHome) {
+        if (!request.routes.some((route) => route.mode === "vector")) {
+            return undefined;
+        }
+        if (this.embeddingModel) {
+            return this.embeddingModel;
+        }
+        return this.recoverEmbeddingModel(schema, registryHome);
+    }
+    embeddingModelForIndex(existing, registryHome, operation) {
+        if (existing && !this.embeddingModelExplicit) {
+            return this.recoverEmbeddingModel(existing.embedding, registryHome);
+        }
+        return this.requireEmbeddingModel(operation);
+    }
+    recoverEmbeddingModel(schema, registryHome) {
+        const key = `${schema.provider}/${schema.model}/${modelCacheDir(this.options, this.root, registryHome)}`;
+        const cached = this.recoveredEmbeddingModels.get(key);
+        if (cached) {
+            return cached;
+        }
+        const model = createEmbeddingModel({
+            provider: schema.provider,
+            model: schema.model,
+        }, providerOptions(this.options, this.root, registryHome));
+        this.recoveredEmbeddingModels.set(key, model);
+        return model;
+    }
+    requireEmbeddingModel(operation) {
+        if (!this.embeddingModel) {
+            throw new EngineError("zvec-grep operation requires an embedding model", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.EMBEDDING_MODEL_REQUIRED",
+                context: errorDetails([
+                    detail("operation", operation),
+                    detail("hint", 'Pass "--embedding <model>" or set ZVEC_GREP_EMBEDDING. Existing indexes can rerun init without --embedding to reuse the stored schema.'),
+                    detail("examples", "local/embeddinggemma-300m, qwen/text-embedding-v4"),
+                ]),
+            });
+        }
+        return this.embeddingModel;
+    }
+    ensureOpen() {
+        if (this.closed) {
+            throw new EngineError("zvec-grep service is already closed", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.CLOSED",
+            });
+        }
+    }
+}
+async function withHomeReadLock(home, operation, task) {
+    const lock = acquireHomeLock(home, "read", operation);
+    try {
+        return await task();
+    }
+    finally {
+        lock.release();
+    }
+}
+async function withHomeWriteLock(home, operation, task) {
+    const lock = acquireHomeLock(home, "write", operation);
+    try {
+        return await task();
+    }
+    finally {
+        lock.release();
+    }
+}
+async function collectionNeedsRefresh(home, collectionName) {
+    const registry = new CollectionRegistry(home, undefined, true);
+    try {
+        const status = await registry.status(collectionName);
+        return status ? collectionIndexStatusNeedsRefresh(status) : false;
+    }
+    finally {
+        registry.close();
+    }
+}
+function collectionIndexStatusNeedsRefresh(status) {
+    return status.filesAdded > 0
+        || status.filesModified > 0
+        || status.filesDeleted > 0
+        || status.filesPending > 0
+        || status.filesFailed > 0;
+}
+function acquireHomeLock(home, mode, operation) {
+    return acquireReadWriteLock(homeLockPath(home), mode, { operation });
+}
+function assertHomeUnlocked(home, operation) {
+    assertNoWriteLock(homeLockPath(home), operation);
+}
+function assertNearestAnonymousHomeUnlocked(start, operation) {
+    let current = resolve(start);
+    while (true) {
+        assertHomeUnlocked(anonymousHome(current), operation);
+        const parent = dirname(current);
+        if (parent === current) {
+            return;
+        }
+        current = parent;
+    }
+}
+function homeLockPath(home) {
+    return join(home, "locks", "home");
+}
+function serviceHome(options) {
+    return options.home ?? defaultHome();
+}
+function rgEmptyReason(diagnostics) {
+    return diagnostics.missingPaths && diagnostics.missingPaths.length > 0
+        && diagnostics.searchedPaths
+        && diagnostics.searchedPaths.length === 0
+        ? "no_searchable_files"
+        : "no_matches";
+}
+function anonymousIndexNotFoundError(root) {
+    return new EngineError("No anonymous zvec-grep index found for this workspace", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.ANONYMOUS_INDEX_NOT_FOUND",
+        context: errorDetails([
+            detail("root", root),
+            detail("hint", 'Run "zg --init" first, or use "zg --rg" for explicit literal/regex search.'),
+        ]),
+    });
+}
+function resolveIndexRootPaths(existing, requested, fallbackRoot, options) {
+    let rootPaths = requested
+        ?? existing?.rootPaths
+        ?? [fallbackRoot];
+    if (options.resetPaths) {
+        rootPaths = rootPaths.map(resetRootPathFilters);
+    }
+    if (options.includePaths !== undefined || options.excludePaths !== undefined) {
+        rootPaths = rootPaths.map((rootPath) => applyRootPathFilterOverrides(rootPath, options.includePaths, options.excludePaths));
+    }
+    return rootPaths;
+}
+function resetRootPathFilters(rootPath) {
+    if (typeof rootPath === "string") {
+        return rootPath;
+    }
+    return {
+        absolutePath: rootPath.absolutePath,
+        recursive: rootPath.recursive,
+    };
+}
+function applyRootPathFilterOverrides(rootPath, include, exclude) {
+    const normalized = typeof rootPath === "string"
+        ? {
+            absolutePath: rootPath,
+            recursive: true,
+        }
+        : rootPath;
+    return {
+        ...normalized,
+        include: include ?? normalized.include,
+        exclude: exclude ?? normalized.exclude,
+    };
+}
+function resolveEmbeddingModel(options, root) {
+    if (options.embeddingModel) {
+        return options.embeddingModel;
+    }
+    if (options.embedding) {
+        return createEmbeddingModelFromReference(options.embedding, providerOptions(options, root));
+    }
+    if (options.defaultEmbedding === true) {
+        return createEmbeddingModelFromReference(DEFAULT_LOCAL_EMBEDDING, providerOptions(options, root));
+    }
+    return undefined;
+}
+function hasExplicitEmbeddingModel(options) {
+    return options.embeddingModel !== undefined
+        || options.embedding !== undefined;
+}
+function readCollectionInfo(home, name) {
+    const registry = new CollectionRegistry(home, undefined, true);
+    try {
+        return registry.get(name);
+    }
+    finally {
+        registry.close();
+    }
+}
+function providerOptions(options, root, registryHome) {
+    return {
+        apiKey: options.apiKey ?? "",
+        endpoint: options.endpoint,
+        modelCacheDir: modelCacheDir(options, root, registryHome),
+        llamaGpu: options.llamaGpu,
+        embeddingParallelism: options.embeddingParallelism,
+    };
+}
+function assertCollectionEmbeddingMatchesCurrentModel(info, model, rebuildCommand) {
+    if (!info) {
+        return;
+    }
+    const expected = info.embedding;
+    const changed = expected.provider !== model.ref.provider
+        || expected.model !== model.ref.model
+        || expected.dimension !== model.dimension
+        || expected.metric !== model.metric;
+    if (!changed) {
+        return;
+    }
+    throw new EngineError("Existing zvec-grep index uses a different embedding model", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.EMBEDDING_SCHEMA_CHANGE_REQUIRES_REBUILD",
+        context: errorDetails([
+            collectionDetail(info.name),
+            detail("existing", `${expected.provider}/${expected.model}`),
+            detail("requested", `${model.ref.provider}/${model.ref.model}`),
+            detail("hint", `Run "${rebuildCommand}" to rebuild this index with the requested embedding model.`),
+        ]),
+    });
+}
+function modelCacheDir(options, root, registryHome) {
+    if (options.modelCacheDir || process.env.ZVEC_GREP_MODEL_CACHE) {
+        return options.modelCacheDir ?? process.env.ZVEC_GREP_MODEL_CACHE;
+    }
+    const globalCache = join(options.home ?? defaultHome(), "models");
+    const legacyCaches = [
+        registryHome ? join(registryHome, "models") : undefined,
+        join(anonymousHome(root), "models"),
+    ];
+    const globalHasModel = directoryHasGguf(globalCache);
+    for (const legacyCache of legacyCaches) {
+        if (legacyCache && directoryHasGguf(legacyCache) && !globalHasModel) {
+            return legacyCache;
+        }
+    }
+    if (globalHasModel || canWriteCacheDirectory(globalCache)) {
+        return globalCache;
+    }
+    return join(anonymousHome(root), "models");
+}
+function directoryHasGguf(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true }).some((entry) => entry.isFile() && entry.name.endsWith(".gguf"));
+    }
+    catch {
+        return false;
+    }
+}
+function canWriteCacheDirectory(path) {
+    const probe = join(path, `.zvec-grep-write-test-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    try {
+        mkdirSync(path, { recursive: true });
+        writeFileSync(probe, "");
+        unlinkSync(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function contextGroupLimit(limit, groupCount) {
+    if (limit !== undefined) {
+        return limit;
+    }
+    const safeGroupCount = Math.max(1, groupCount);
+    if (safeGroupCount <= 3) {
+        return DEFAULT_CONTEXT_LIMIT;
+    }
+    return Math.max(1, Math.ceil(DEFAULT_CONTEXT_TOTAL_LIMIT / safeGroupCount));
+}
+function normalizeContextRequest(options) {
+    const primaryQueries = normalizePrimaryQueries(options.query, options.queries);
+    const extraRoutes = normalizeContextRoutes(options.routes ?? []);
+    if (primaryQueries.length === 0 && extraRoutes.length === 0) {
+        throw new EngineError("zvec-grep context requires a non-empty query or route", {
+            code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_QUERY",
+        });
+    }
+    const groups = contextGroups(primaryQueries, extraRoutes);
+    const routes = groups.flatMap((group) => group.routes);
+    const fallbackQueries = groups.map((group) => group.fallbackQuery);
+    const displayQuery = primaryQueries.length > 0
+        ? primaryQueries.join(" | ")
+        : extraRoutes.map((route) => route.query).join(" | ");
+    return {
+        displayQuery,
+        fallbackQueries,
+        routes,
+        groups,
+    };
+}
+function normalizePrimaryQueries(query, queries) {
+    return [
+        query,
+        ...(queries ?? []),
+    ].flatMap((value) => {
+        const normalized = normalizeOptionalQuery(value);
+        return normalized ? [normalized] : [];
+    });
+}
+function normalizeOptionalQuery(query) {
+    const normalized = query?.trim() ?? "";
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeContextRoutes(routes) {
+    return routes.map((route, index) => {
+        if (route.mode !== "fts" && route.mode !== "vector") {
+            throw new EngineError("zvec-grep context route has an unsupported mode", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.INVALID_ROUTE_MODE",
+                context: `routeIndex=${index} mode=${String(route.mode)}`,
+            });
+        }
+        const query = route.query.trim();
+        if (query.length === 0) {
+            throw new EngineError("zvec-grep context route requires a non-empty query", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_ROUTE_QUERY",
+                context: `routeIndex=${index} mode=${route.mode}`,
+            });
+        }
+        return {
+            mode: route.mode,
+            query,
+        };
+    });
+}
+function contextGroups(primaryQueries, extraRoutes) {
+    return [
+        ...primaryQueries.map((query) => ({
+            routes: [
+                { mode: "fts", query },
+                { mode: "vector", query },
+            ],
+            fallbackQuery: query,
+        })),
+        ...extraRoutes.map((route) => ({
+            routes: [route],
+            fallbackQuery: route.query,
+        })),
+    ];
+}
+function searchPlanToContextItems(result, root) {
+    return result.hits.map((hit) => {
+        const target = contextItemTarget(hit);
+        return {
+            kind: "indexed_entity",
+            rank: hit.rank,
+            file: {
+                absolutePath: hit.file.absolutePath,
+                relativePath: hit.file.relativePath || relative(root, hit.file.absolutePath) || ".",
+                rootPath: hit.file.rootPath,
+            },
+            range: hit.entity.range,
+            excerptRange: target.excerptRange,
+            content: contentToText(target.content),
+            contentRole: target.contentRole,
+            outline: target.outline,
+            status: fileFreshnessStatus(hit.file),
+            score: hit.score,
+            matchedBy: hit.matchedBy,
+            metadata: hit.entity.metadata,
+            entityId: hit.entity.id,
+            trace: hit.trace,
+        };
+    });
+}
+function dedupeAndRerankContextItems(items) {
+    const seen = new Set();
+    const deduped = [];
+    for (const item of items) {
+        const key = contextItemDedupeKey(item);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push({
+            ...item,
+            rank: deduped.length + 1,
+        });
+    }
+    return deduped;
+}
+function contextItemDedupeKey(item) {
+    if (item.entityId) {
+        return `entity:${item.entityId}`;
+    }
+    return [
+        "range",
+        item.file.absolutePath,
+        JSON.stringify(item.range),
+    ].join(":");
+}
+function mergeFallbackDiagnostics(results) {
+    const [first] = results;
+    if (!first) {
+        throw new EngineError("zvec-grep lexical fallback requires at least one query", {
+            code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_QUERY",
+        });
+    }
+    return {
+        ...first.diagnostics,
+        truncated: results.some((result) => result.diagnostics.truncated),
+    };
+}
+function contextItemTarget(hit) {
+    const evidence = hit.evidence.find((item) => !item.isEntity);
+    const hasSeparateEvidence = evidence && !sameDisplayedContent(hit.entity, evidence);
+    const content = hasSeparateEvidence ? evidence.content : hit.entity.content;
+    const contentRole = hasSeparateEvidence || entityContentLooksLikeSource(hit.entity)
+        ? "source"
+        : "outline";
+    const excerptRange = hasSeparateEvidence ? evidence.range : undefined;
+    const outline = contentRole === "source" ? contextItemOutline(hit, evidence) : undefined;
+    return {
+        content,
+        contentRole,
+        excerptRange,
+        outline,
+    };
+}
+function entityContentLooksLikeSource(entity) {
+    if (entity.content.kind !== "text" || entity.range.kind !== "text") {
+        return true;
+    }
+    const expectedLines = entity.range.endLine - entity.range.startLine + 1;
+    const actualLines = entity.content.text.split(/\r?\n/).length;
+    return actualLines >= expectedLines;
+}
+function contextItemOutline(hit, evidence) {
+    if (hit.entity.content.kind !== "text") {
+        return undefined;
+    }
+    const outline = hit.entity.content.text.trim();
+    if (outline.length === 0) {
+        return undefined;
+    }
+    if (!evidence) {
+        return undefined;
+    }
+    if (evidence && sameDisplayedContent(hit.entity, evidence)) {
+        return undefined;
+    }
+    if (!isUsefulOutline(hit.entity.metadata, outline)) {
+        return undefined;
+    }
+    if (evidence?.content.kind === "text" && evidence.content.text.trim() === outline) {
+        return undefined;
+    }
+    return outline;
+}
+function isUsefulOutline(metadata, outline) {
+    if (!metadata || metadata.kind !== "code") {
+        return false;
+    }
+    return metadata.symbolType === "class"
+        || metadata.symbolType === "interface"
+        || metadata.symbolType === "module"
+        || outline.includes("\ncalls:");
+}
+function sameDisplayedContent(entity, evidence) {
+    return JSON.stringify(entity.range) === JSON.stringify(evidence.range)
+        && contentEquals(entity.content, evidence.content);
+}
+function contentEquals(left, right) {
+    if (left.kind !== right.kind) {
+        return false;
+    }
+    if (left.kind === "image") {
+        return right.kind === "image"
+            && left.format === right.format
+            && left.data.byteLength === right.data.byteLength;
+    }
+    return right.kind === "text" && left.text === right.text;
+}
+function fileFreshnessStatus(file) {
+    if (!file.indexStatus?.indexedTime) {
+        return "possibly_stale";
+    }
+    try {
+        const info = statSync(file.absolutePath, { throwIfNoEntry: false });
+        if (!info || !info.isFile()) {
+            return "possibly_stale";
+        }
+        if (file.indexStatus.indexedTime >= info.mtimeMs) {
+            return "fresh";
+        }
+        if (file.contentHash && sha256File(file.absolutePath) === file.contentHash) {
+            return "fresh";
+        }
+    }
+    catch {
+        return "possibly_stale";
+    }
+    return "possibly_stale";
+}
+function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function contentToText(content) {
+    if (content.kind === "text") {
+        return content.text;
+    }
+    return `[image:${content.format} bytes=${content.data.byteLength}]`;
+}
+//# sourceMappingURL=zvec-grep.js.map