@untangle-code/cli 0.0.0-stage → 0.1.0

package/dist/commands/query.js

@@ -0,0 +1,783 @@
+/**
+ * `untangle query` — der Befehl, um den es geht.
+ *
+ * Er verdrahtet @untangle-code/search und macht dabei ZWEI Dinge unter EINER
+ * Oberflaeche sichtbar (Nutzerwunsch A4):
+ *
+ *   - die SEMANTISCHE Suche (hybrid aus dichtem Vektor, BM25 und exaktem
+ *     Symbolnamen, fusioniert per RRF), und
+ *   - die GREP-artige Suche (Literal oder regulaerer Ausdruck) mit
+ *     Kontextzeilen, Pfad-Ein-/Ausschluss und Trefferbegrenzung.
+ *
+ * `--explain` ist kein Debug-Anhang, sondern der Kern von vision.md §1d: die
+ * Score-Zerlegung beantwortet „warum steht das oben?" — und damit auch die
+ * Gegenfrage „warum steht der richtige Treffer NICHT oben?".
+ *
+ * WICHTIG UND EHRLICH: Gesucht wird im INDEX, nicht auf der Platte. Solange
+ * `untangle index` fehlt (siehe dort), ist der Index leer. Dieser Befehl
+ * behauptet dann nicht „nichts gefunden", sondern nennt den fehlenden Index
+ * als Grund und endet mit Exit-Code 4.
+ */
+import path from "node:path";
+import { OfflineEmbeddingProvider } from "@untangle-code/core";
+import { compareCodepoints, isUntangleError, embeddingProfileShortId, INDEX_CONTEXT_INCOMPLETE_WARNING_CODE, uniqueSortedByCodepoints, } from "@untangle-code/domain";
+import { COMPLEXITY_BIASES, GREP_SORTS, NO_SUFFICIENT_MATCH_WARNING_CODE, OUTPUT_FORMATS, SEARCH_ABSTENTIONS, SEARCH_MODES, SEARCH_SORTS, formatGrepResultSet, formatHitAsText, formatSearchGraphRelationsAsText, formatSearchResultSet, } from "@untangle-code/search";
+import { codeCollectionName } from "@untangle-code/storage-qdrant";
+import { boolFlag, enumFlag, integerFlag, listFlag, numberFlag, stringFlag, } from "../cli/args.js";
+import { withDeadline } from "../cli/deadline.js";
+import { EXIT, EnvironmentError, OperationalError, UsageError } from "../cli/exit.js";
+import { inspectIndexFreshness } from "../cli/index-freshness.js";
+import { refreshWorkspaceIndex } from "../cli/index-refresh.js";
+import { resolveIndexState, } from "../cli/index-state.js";
+import { line, note } from "../cli/io.js";
+import { createSearchGraphEnrichment } from "../cli/search-graph-enrichment.js";
+import { systemClock } from "../cli/system.js";
+import { errorMessage, loadWorkspace, wireEmbedder, wireSearchEngine, wireStorage, matchesStoredBackend, storageIndexScope, } from "../cli/workspace.js";
+/**
+ * Frist der ganzen Anfrage.
+ *
+ * Includes retrieval and optional graph enrichment. Semantic/hybrid search
+ * also computes a query embedding, which can require loading a service model.
+ * The finite deadline keeps an unresponsive terminal from hanging indefinitely.
+ */
+export const DEFAULT_QUERY_TIMEOUT_MS = 60_000;
+const FLAGS = {
+    embedder: {
+        kind: "string",
+        placeholder: "auto|service|offline",
+        describe: "auto selects the last index run's profile; service forces the configured service, offline selects the locally built collection.",
+        defaultLabel: "auto",
+    },
+    root: {
+        kind: "string",
+        placeholder: "PATH",
+        describe: "Project directory; configuration is discovered from here.",
+        defaultLabel: "current directory",
+    },
+    format: {
+        kind: "string",
+        placeholder: OUTPUT_FORMATS.join("|"),
+        describe: "Output format. jsonl is streamable; json contains the complete result.",
+        defaultLabel: "text",
+    },
+    limit: { kind: "number", alias: "n", placeholder: "N", describe: "Number of results." },
+    explain: {
+        kind: "boolean",
+        describe: "Show each result's score breakdown (vision.md §1d).",
+    },
+    mode: {
+        kind: "string",
+        placeholder: SEARCH_MODES.join("|"),
+        describe: "Independent retrieval and ranking paths: lexical/symbol require no embedding.",
+        defaultLabel: "hybrid",
+    },
+    abstention: {
+        kind: "string",
+        placeholder: SEARCH_ABSTENTIONS.join("|"),
+        describe: "Behavior with insufficient evidence: strict returns no hits; evidence returns hits with the verdict.",
+        defaultLabel: "strict",
+    },
+    sort: {
+        kind: "string",
+        placeholder: SEARCH_SORTS.join("|"),
+        describe: "Result sort key.",
+        defaultLabel: "relevance",
+    },
+    content: { kind: "boolean", describe: "Include chunk content (token-intensive)." },
+    linked: {
+        kind: "boolean",
+        describe: "Direct, unambiguously resolved relationships from the persisted symbol graph.",
+    },
+    "min-score": {
+        kind: "number",
+        placeholder: "X",
+        describe: "Discard results below this score.",
+    },
+    "complexity-bias": {
+        kind: "string",
+        placeholder: COMPLEXITY_BIASES.join("|"),
+        describe: "Prefer simpler or more complex results (vision.md §1b).",
+        defaultLabel: "none",
+    },
+    path: {
+        kind: "list",
+        placeholder: "GLOB",
+        describe: "Include these paths only. Repeatable.",
+    },
+    exclude: {
+        kind: "list",
+        placeholder: "GLOB",
+        describe: "Exclude these paths. Repeatable.",
+    },
+    lang: { kind: "list", placeholder: "ID", describe: "Include these languages only. Repeatable." },
+    repo: {
+        kind: "list",
+        placeholder: "ID",
+        describe: "Include these repositories only. Repeatable.",
+    },
+    ref: { kind: "list", placeholder: "ID", describe: "Include these refs only. Repeatable." },
+    symbol: { kind: "list", placeholder: "NAME", describe: "Exact symbol names. Repeatable." },
+    workspace: { kind: "string", placeholder: "ID", describe: "Override workspace ID." },
+    timeout: {
+        kind: "number",
+        placeholder: "MS",
+        describe: "Deadline for the entire query. Expiry makes the query fail.",
+        defaultLabel: String(DEFAULT_QUERY_TIMEOUT_MS),
+    },
+    refresh: {
+        kind: "boolean",
+        describe: "Refresh stale checked-out refs before searching; progress goes to stderr.",
+    },
+    "require-fresh": {
+        kind: "boolean",
+        describe: "Search only with confirmed current content hashes; otherwise exit 4.",
+    },
+    // --- grep-Modus (Nutzerwunsch A4) ---------------------------------------
+    grep: {
+        kind: "boolean",
+        alias: "g",
+        describe: "grep mode: literal search in indexed content.",
+    },
+    regex: { kind: "boolean", alias: "e", describe: "grep mode with a regular expression." },
+    "ignore-case": {
+        kind: "boolean",
+        alias: "i",
+        describe: "grep: ignore letter case.",
+    },
+    word: {
+        kind: "boolean",
+        alias: "w",
+        describe: "grep: whole words only (identifier boundaries).",
+    },
+    after: {
+        kind: "number",
+        alias: "A",
+        placeholder: "N",
+        describe: "grep: context lines after the match.",
+    },
+    before: {
+        kind: "number",
+        alias: "B",
+        placeholder: "N",
+        describe: "grep: context lines before the match.",
+    },
+    context: {
+        kind: "boolean-or-number",
+        alias: "C",
+        placeholder: "N",
+        describe: "Search: direct relationships from the persisted file graph. grep: =N or -C N shows context on both sides.",
+    },
+    "max-matches": {
+        kind: "number",
+        placeholder: "N",
+        describe: "grep: maximum total matches.",
+    },
+    "max-per-file": { kind: "number", placeholder: "N", describe: "grep: maximum matches per file." },
+    "max-scanned": {
+        kind: "number",
+        placeholder: "N",
+        describe: "grep: maximum searched chunks.",
+    },
+    "grep-sort": {
+        kind: "string",
+        placeholder: GREP_SORTS.join("|"),
+        describe: "grep: match ordering.",
+        defaultLabel: "path",
+    },
+};
+export const queryCommand = {
+    spec: {
+        name: "query",
+        implementedBy: "commands/query.js",
+        summary: "Search the index with semantic and grep-style queries",
+        usage: "untangle query <text> [options]",
+        details: [
+            "Without --grep/--regex, hybrid search retrieves dense vectors, BM25 and exact symbols independently, then combines them with RRF. --mode selects independent retrieval and ranking paths; lexical/symbol need no embedding service.",
+            "Before each search, index freshness is checked against the full current content manifest and returned as indexFreshness. --refresh updates stale checked-out refs; --require-fresh rejects unconfirmed freshness. An outdated lexical index format requires reindexing.",
+            "--grep (literal) and --regex search the same index with the same filters and skip ledger. Context lines come from the same chunk and stop at its boundary.",
+            "--explain shows the full score breakdown: each component's raw value, weight and contribution, making the ranking inspectable.",
+            "Profile discovery: `untangle index` records the embedding profile per repository/ref in the local registry (.untangle/index-states-v1). Without --embedder, query uses the generation-bound current state and reports that choice on stderr. Override with --embedder=service or --embedder=offline.",
+            "Search reads the index, not the working tree. Unindexed content cannot be found; the result therefore includes its skip ledger and, for grep, the number of searched chunks.",
+        ],
+        flags: FLAGS,
+        examples: [
+            'untangle query "where is the payment triggered"',
+            'untangle query "charge" --mode=symbol --explain',
+            "untangle query --regex \"await\\\\s+fetch\\\\(\" -C 2 --path='src/**' --exclude='**/*.test.ts'",
+            'untangle query "retry" --format=jsonl | jq -r .filePath',
+        ],
+        exitCodes: [
+            [EXIT.ok, "Search completed, including zero-hit results."],
+            [EXIT.operational, "Invalid configuration or a storage error."],
+            [EXIT.usage, "Invalid arguments."],
+            [
+                EXIT.environment,
+                "No compatible index, or the selected storage/embedding provider is unavailable.",
+            ],
+            [EXIT.cancelled, "Cancelled."],
+        ],
+    },
+    async run(ctx, args) {
+        const format = enumFlag(args, "format", OUTPUT_FORMATS, "text");
+        const isGrep = boolFlag(args, "grep") || boolFlag(args, "regex");
+        const text = args.positionals.join(" ").trim();
+        if (text.length === 0) {
+            throw new UsageError("Search text is required.", isGrep
+                ? 'Example: untangle query --regex "await\\\\s+fetch\\\\("'
+                : 'Example: untangle query "where is the payment triggered"');
+        }
+        const view = loadWorkspace({
+            cwd: args.flags["root"] === undefined ? ctx.cwd : String(args.flags["root"]),
+            env: ctx.env,
+            workspaceIdOverride: stringFlag(args, "workspace"),
+            strict: true,
+        });
+        if (view.load.warnings.length > 0) {
+            for (const warning of view.load.warnings) {
+                note(ctx.io, `Configuration warning: ${warning.path || "(root)"}: ${warning.message}`);
+            }
+        }
+        const wiring = wireStorage(view, ctx.env);
+        const timeoutMs = integerFlag(args, "timeout", DEFAULT_QUERY_TIMEOUT_MS);
+        // `untangle index --embedder=offline` legt seine Punkte in einer EIGENEN
+        // Sammlung ab (eigener `embedding_profile_id`, spec.md §10.1) — sonst
+        // mischten netzlose und echte Vektoren in einem Raum, in dem sie nicht
+        // vergleichbar sind. Damit dieser Index auch DURCHSUCHBAR ist, kennt
+        // `query` denselben Schalter.
+        //
+        // WP-229: Ihn zu KENNEN reichte aber nicht — man musste ihn auch bei jeder
+        // Abfrage wiederholen. `auto` liest deshalb den Indexzustand, den
+        // `untangle index` hinterlaesst, und nimmt von dort, WOMIT tatsaechlich
+        // indiziert wurde. Geraten wird nichts: gibt es keinen Zustand, gilt die
+        // Konfiguration wie bisher, und widersprechen sich mehrere, sagt der
+        // Befehl das und laesst den Nutzer entscheiden.
+        const selectedRepoIds = listFlag(args, "repo");
+        const selectedRefIds = listFlag(args, "ref");
+        const indexStateResolution = await resolveIndexState(indexStateRoots({
+            invocationRoot: args.flags["root"] === undefined
+                ? ctx.cwd
+                : path.resolve(ctx.cwd, String(args.flags["root"])),
+            configBaseDir: view.load.sources.configBaseDir,
+            repositories: view.config.repositories ?? [],
+            selectedRepoIds,
+        }), view.workspaceId, { repoIds: selectedRepoIds, refs: selectedRefIds, ...storageIndexScope(wiring) });
+        if (indexStateResolution.kind === "invalid") {
+            const details = indexStateResolution.diagnostics
+                .map((diagnostic) => `${diagnostic.path}: ${diagnostic.message}`)
+                .join("; ");
+            throw new EnvironmentError(`The local index state is invalid; search will not use partial or ` +
+                `stale provenance. ${details}`, "Rerun the affected indexing job. It publishes the repository/ref registry atomically.");
+        }
+        const automaticEmbedder = enumFlag(args, "embedder", ["auto", "service", "offline"], "auto") === "auto";
+        const useOffline = resolveEmbedderChoice(ctx, args, indexStateResolution);
+        const embedder = useOffline ? new OfflineEmbeddingProvider(systemClock) : wireEmbedder(view);
+        const searchView = useOffline
+            ? {
+                ...view,
+                profile: embedder.profile,
+                profileId: embedder.profileId,
+                profileShortId: embeddingProfileShortId(embedder.profileId),
+            }
+            : view;
+        const collection = useOffline
+            ? codeCollectionName(wiring.collectionPrefix, searchView.profileShortId)
+            : wiring.codeCollection;
+        const foundIndexStates = queryIndexStatesFromResolution(indexStateResolution, automaticEmbedder);
+        const compatibleIndexStates = foundIndexStates.filter(({ state }) => state.embeddingProfileId === searchView.profileId &&
+            state.collection === collection &&
+            matchesStoredBackend(state, wiring));
+        const freshnessCheck = await withDeadline((signal) => inspectIndexFreshness(view, compatibleIndexStates, {
+            signal,
+            expectedRepoIds: selectedRepoIds.length > 0 ? selectedRepoIds : view.repoIds,
+            expectedRefs: selectedRefIds,
+        }), timeoutMs, ctx.signal);
+        ctx.signal.throwIfAborted();
+        const indexFreshness = freshnessCheck.ok
+            ? freshnessCheck.value
+            : {
+                status: "unknown",
+                checkedAt: systemClock.nowIso(),
+                repositories: [],
+            };
+        if (boolFlag(args, "refresh") && indexFreshness.status !== "fresh") {
+            await refreshWorkspaceIndex(ctx, {
+                view,
+                repoIds: selectedRepoIds,
+                refIds: selectedRefIds,
+                embedder: useOffline ? "offline" : "auto",
+            });
+            return queryCommand.run(ctx, {
+                ...args,
+                flags: { ...args.flags, refresh: false, "require-fresh": true },
+            });
+        }
+        if (indexFreshness.status === "incompatible" ||
+            (boolFlag(args, "require-fresh") && indexFreshness.status !== "fresh")) {
+            throw new EnvironmentError(`The search index is ${indexFreshness.status}; this query requires a current, compatible index.`, "Run the same query with --refresh or update with `untangle index`.");
+        }
+        note(ctx.io, `Index freshness: ${indexFreshness.status} (content hashes checked ${indexFreshness.checkedAt}).`);
+        const indexContexts = compatibleIndexStates.flatMap(({ state }) => state.generationId !== undefined
+            ? [
+                {
+                    repoId: state.repoId,
+                    refId: state.refId,
+                    generationId: state.generationId,
+                    ...(state.corpusRevisionFingerprint === undefined || indexFreshness.status !== "fresh"
+                        ? {}
+                        : { corpusRevisionFingerprint: state.corpusRevisionFingerprint }),
+                    outcome: state.outcome,
+                },
+            ]
+            : []);
+        const effectiveRefIds = queryRefIdsFromIndexStates(selectedRefIds, compatibleIndexStates);
+        // Der fehlende Index ist der haeufigste Fall und verdient eine eigene,
+        // eindeutige Antwort — nicht eine leere Trefferliste (E4).
+        const probe = await withDeadline((signal) => wiring.vectorStore.collectionExists(collection, { signal }), timeoutMs, ctx.signal);
+        if (!probe.ok) {
+            ctx.signal.throwIfAborted();
+            throw new EnvironmentError(probe.timedOut
+                ? `${wiring.backend === "qdrant" ? "Qdrant" : "LanceDB"} at ${wiring.storeUrl} did not answer within ${String(timeoutMs)}ms.`
+                : `${wiring.backend === "qdrant" ? "Qdrant" : "LanceDB"} at ${wiring.storeUrl} is unreachable: ${errorMessage(probe.error)}`, "Run `untangle doctor` for the next step specific to this failure.", { cause: probe.error });
+        }
+        if (!probe.value) {
+            if (boolFlag(args, "refresh")) {
+                await refreshWorkspaceIndex(ctx, {
+                    view,
+                    repoIds: selectedRepoIds,
+                    refIds: selectedRefIds,
+                    embedder: useOffline ? "offline" : "auto",
+                });
+                return queryCommand.run(ctx, {
+                    ...args,
+                    flags: { ...args.flags, refresh: false, "require-fresh": true },
+                });
+            }
+            throw new EnvironmentError(`No index exists for this embedding profile: collection "${collection}" ` +
+                `is absent from ${wiring.storeUrl}. Nothing was searched; this does not ` +
+                `mean there are no results.`, useOffline
+                ? "Run `untangle index --embedder=offline` to build this collection."
+                : "Run `untangle index`. Without an available embedding service, use `untangle index --embedder=offline` and select `--embedder=offline` here too.");
+        }
+        const engine = wireSearchEngine({
+            view: searchView,
+            vectorStore: wiring.vectorStore,
+            collection,
+            embedder,
+            indexContexts,
+            ...(!isGrep && (boolFlag(args, "context") || boolFlag(args, "linked"))
+                ? { graphEnrichment: createSearchGraphEnrichment(wiring.storage.graphStore) }
+                : {}),
+        });
+        if (isGrep) {
+            const request = buildGrepRequest(args, view.workspaceId, text, effectiveRefIds);
+            const outcome = await withDeadline((signal) => engine.grep(request, { signal }), timeoutMs, ctx.signal);
+            if (!outcome.ok) {
+                ctx.signal.throwIfAborted();
+                throw toRuntimeError(outcome, wiring.storeUrl, timeoutMs, "grep", useOffline);
+            }
+            outcome.value.indexFreshness = indexFreshness;
+            addFreshnessWarning(outcome.value, indexFreshness);
+            renderGrep(ctx, outcome.value, format);
+            assertEverythingWasSearched(ctx, outcome.value.skipped, wiring.backend);
+            return EXIT.ok;
+        }
+        const request = buildSearchRequest(args, view.workspaceId, text, selectedRefIds.length === 0 ? undefined : effectiveRefIds);
+        const outcome = await withDeadline((signal) => engine.search(request, { signal }), timeoutMs, ctx.signal);
+        if (!outcome.ok) {
+            ctx.signal.throwIfAborted();
+            throw toRuntimeError(outcome, wiring.storeUrl, timeoutMs, request, useOffline);
+        }
+        outcome.value.indexFreshness = indexFreshness;
+        addFreshnessWarning(outcome.value, indexFreshness);
+        renderSearch(ctx, outcome.value, format, boolFlag(args, "explain"));
+        assertEverythingWasSearched(ctx, outcome.value.skipped, wiring.backend);
+        return EXIT.ok;
+    },
+};
+/* --------------------------------------------------------------------- */
+export function addFreshnessWarning(result, freshness) {
+    if (freshness.status === "fresh")
+        return;
+    const warning = {
+        code: INDEX_CONTEXT_INCOMPLETE_WARNING_CODE,
+        message: `Indexfrische ${freshness.status}: results describe an unconfirmed or stale snapshot. Update with --refresh. This query is not reliable product-complexity evidence.`,
+        details: {
+            status: freshness.status,
+            checkedAt: freshness.checkedAt,
+            reasons: freshness.repositories.map((entry) => entry.reason),
+        },
+    };
+    const existingIndex = result.warnings.findIndex((entry) => entry.code === INDEX_CONTEXT_INCOMPLETE_WARNING_CODE);
+    const existing = result.warnings[existingIndex];
+    if (existing === undefined)
+        result.warnings.push(warning);
+    else
+        result.warnings[existingIndex] = {
+            ...existing,
+            message: `${existing.message} ${warning.message}`,
+            details: { ...existing.details, indexFreshness: warning.details },
+        };
+}
+/**
+ * Welcher Einbetter durchsucht wird — und woher diese Entscheidung stammt
+ * (WP-229).
+ *
+ * `--embedder=offline` und `--embedder=service` sind ausdrueckliche
+ * Anweisungen und gewinnen immer. `auto` fragt den Indexzustand: er ist die
+ * einzige Quelle, die WEISS, womit gebaut wurde. Was dabei entschieden wird,
+ * steht auf stderr — eine Wahl, die der Nutzer nicht sieht, ist eine Wahl,
+ * die er nicht ueberstimmen kann.
+ */
+export function resolveEmbedderChoice(ctx, args, resolution) {
+    const flag = enumFlag(args, "embedder", ["auto", "service", "offline"], "auto");
+    if (flag === "offline")
+        return true;
+    if (flag === "service")
+        return false;
+    if (resolution.kind === "none") {
+        // Kein Zustand heisst: es wurde hier noch nicht indiziert, oder mit einer
+        // aelteren Fassung. Dann gilt die Konfiguration — und wenn dazu kein Index
+        // existiert, meldet das der Aufrufer mit der Begruendung, die es schon gab.
+        return false;
+    }
+    if (resolution.kind === "ambiguous") {
+        const states = resolution.found
+            .map((entry) => `${entry.state.repoId}/${entry.state.refName}: ${entry.state.embedder}`)
+            .join(", ");
+        throw new UsageError("The current repository/ref states use different embedders; `auto` " +
+            `would search only a subset (${states}). Select --embedder=service or ` +
+            "--embedder=offline explicitly.", "An explicit selection searches only locally registered refs for that profile.");
+    }
+    if (resolution.kind === "invalid") {
+        // The command rejects this case before selecting an embedder. Keeping the
+        // guard here makes the helper exhaustive if it is reused independently.
+        throw new EnvironmentError("The local index state is invalid; the embedding profile will not be guessed.", "Rerun the affected indexing job.");
+    }
+    const state = resolution.found.state;
+    note(ctx.io, `Embedding profile from the last index run: ${describeEmbedder(state.embedder)} ` +
+        `(${resolution.found.statePath}). ` +
+        "Override with --embedder=service or --embedder=offline.");
+    if (state.outcome !== "completed") {
+        note(ctx.io, `Warning: this indexing run ended as "${state.outcome}". Anything it could not finish ` +
+            "cannot be found here either.");
+    }
+    return state.embedder === "offline";
+}
+/**
+ * Wo nach dem Indexzustand gesucht wird. Ohne Repo-Filter gilt die bisherige
+ * Reihenfolge: Aufrufswurzel, Konfigurationswurzel, dann alle konfigurierten
+ * Repositories codepoint-sortiert. Mit `--repo` duerfen dagegen nur die
+ * tatsaechlich ausgewaehlten Repository-Wurzeln die Auto-Embedder-Wahl
+ * beeinflussen; ein unbeteiligtes Repository darf keine Ambiguitaet erzeugen.
+ */
+export function indexStateRoots(input) {
+    const selected = new Set(input.selectedRepoIds);
+    const roots = selected.size === 0 || input.repositories.length === 0
+        ? [input.invocationRoot, input.configBaseDir]
+        : [];
+    const repositories = [...input.repositories]
+        .filter((repository) => selected.size === 0 || selected.has(repository.id))
+        .sort((a, b) => compareCodepoints(a.id, b.id));
+    for (const repository of repositories) {
+        roots.push(path.resolve(input.configBaseDir, repository.path));
+    }
+    return roots;
+}
+/**
+ * Resolves an omitted ref scope to the refs for which the selected collection
+ * has local index state. Explicit canonical IDs remain authoritative; an
+ * explicit human ref name expands to every compatible canonical ID carrying
+ * that name (for example `main` in two selected repositories).
+ *
+ * The grep path receives these IDs directly. Semantic search receives the
+ * richer index contexts and derives the same scope inside the engine, where
+ * it can still distinguish an implicit scope for provenance validation. This
+ * is deliberately based on profile/collection-compatible states supplied by
+ * the caller: an old state for another embedding space must not widen a scan.
+ */
+export function queryRefIdsFromIndexStates(requestedRefIds, compatibleIndexStates) {
+    if (requestedRefIds.length === 0) {
+        return uniqueSortedByCodepoints(compatibleIndexStates.map(({ state }) => state.refId));
+    }
+    const canonicalIds = new Set(compatibleIndexStates.map(({ state }) => state.refId));
+    const resolved = [];
+    for (const requested of requestedRefIds) {
+        if (canonicalIds.has(requested)) {
+            resolved.push(requested);
+            continue;
+        }
+        const nameMatches = compatibleIndexStates
+            .filter(({ state }) => state.refName === requested)
+            .map(({ state }) => state.refId);
+        // Keep an unknown explicit value. It will remain a restrictive store
+        // filter and cannot silently fall back to the implicit/all-ref scope.
+        resolved.push(...(nameMatches.length === 0 ? [requested] : nameMatches));
+    }
+    return uniqueSortedByCodepoints(resolved);
+}
+/**
+ * Auto-routing follows only the generation-checked current pointer of every
+ * selected repo/ref. An explicit embedder selection may intentionally reopen
+ * an older retained profile and therefore receives the complete registry.
+ */
+export function queryIndexStatesFromResolution(resolution, automaticEmbedder) {
+    if (resolution.kind === "none")
+        return [];
+    const all = resolution.all;
+    return automaticEmbedder ? all.filter((entry) => entry.current) : all;
+}
+function describeEmbedder(choice) {
+    return choice === "offline" ? "offline (local, in-process)" : "the configured service";
+}
+/**
+ * Ziele, die ueberhaupt nicht durchsucht werden konnten.
+ *
+ * DIESE UNTERSCHEIDUNG IST DER KERN VON E4 AN DIESER OBERFLAECHE. Der
+ * Abrufkern degradiert bewusst sichtbar: faellt ein Embedding-Profil aus (weil
+ * Ollama nicht antwortet), meldet er das als Warnung UND als Ledger-Eintrag
+ * und liefert die uebrigen Profile trotzdem. Fuer den Aufrufer sieht das
+ * Ergebnis dann aus wie „null Treffer" — und genau das waere die Luege:
+ * gesucht wurde nichts.
+ *
+ * Gemessen an einem blockierten Ollama gab diese Oberflaeche vor der
+ * Einfuehrung dieser Pruefung „Keine Treffer." mit Exit-Code 0 aus, obwohl im
+ * Ledger `provider_unavailable` stand. Jetzt endet derselbe Fall mit
+ * Exit-Code 4 und der Begruendung aus dem Ledger.
+ *
+ * Erkannt wird der Ausfall an der Kombination, die der Abrufkern EXAKT fuer
+ * diesen Fall schreibt: `subjectKind === "search_candidate"` zusammen mit
+ * `reason === "provider_unavailable"`. Ein wegen Filtern oder Budget
+ * ausgelassenes Ziel traegt stattdessen `excluded_by_configuration` und ist
+ * kein Ausfall.
+ */
+export function failedTargets(skipped) {
+    return skipped.filter((entry) => entry.subjectKind === "search_candidate" && entry.reason === "provider_unavailable");
+}
+/** Wirft, wenn ein Ziel ausgefallen ist — „nichts durchsucht" ist kein Erfolg. */
+function assertEverythingWasSearched(ctx, skipped, backend) {
+    const failed = failedTargets(skipped);
+    if (failed.length === 0)
+        return;
+    for (const entry of failed) {
+        note(ctx.io, `Unavailable target: ${entry.detail}`);
+    }
+    throw new EnvironmentError(`${String(failed.length)} search target(s) did not respond. The result above is ` +
+        "incomplete; this does not mean nothing was found.", `Run \`untangle doctor\` to check Ollama and ${backend === "lancedb" ? "LanceDB" : "Qdrant"} independently with separate deadlines.`);
+}
+export function buildSearchRequest(args, workspaceId, text, refIdsOverride) {
+    if (typeof args.flags["context"] === "number") {
+        throw new UsageError('Option "--context=N" applies only in grep mode.', 'For semantic search, use "--context" without a number.');
+    }
+    const limit = numberFlag(args, "limit");
+    const minScore = numberFlag(args, "min-score");
+    const paths = listFlag(args, "path");
+    const excludes = listFlag(args, "exclude");
+    const languages = listFlag(args, "lang");
+    const repositories = listFlag(args, "repo");
+    const refs = refIdsOverride === undefined ? listFlag(args, "ref") : uniqueSortedByCodepoints(refIdsOverride);
+    const symbolNames = listFlag(args, "symbol");
+    return {
+        query: text,
+        workspaceId,
+        ...(limit === undefined ? {} : { limit }),
+        ...(minScore === undefined ? {} : { minScore }),
+        ...(paths.length === 0 ? {} : { pathGlob: paths }),
+        ...(excludes.length === 0 ? {} : { pathExclude: excludes }),
+        ...(languages.length === 0 ? {} : { languages }),
+        ...(repositories.length === 0 ? {} : { repositories }),
+        ...(refs.length === 0 ? {} : { refs }),
+        ...(symbolNames.length === 0 ? {} : { symbolNames }),
+        mode: enumFlag(args, "mode", SEARCH_MODES, "hybrid"),
+        abstention: enumFlag(args, "abstention", SEARCH_ABSTENTIONS, "strict"),
+        sort: enumFlag(args, "sort", SEARCH_SORTS, "relevance"),
+        complexityBias: enumFlag(args, "complexity-bias", COMPLEXITY_BIASES, "none"),
+        includeContent: boolFlag(args, "content"),
+        includeContext: boolFlag(args, "context"),
+        includeLinked: boolFlag(args, "linked"),
+    };
+}
+export function buildGrepRequest(args, workspaceId, pattern, refIdsOverride) {
+    if (args.flags["context"] === true) {
+        throw new UsageError('Option "--context" requires a non-negative integer in grep mode.', 'Example: "--context=2" or "-C 2".');
+    }
+    const both = integerFlag(args, "context", 0);
+    const before = integerFlag(args, "before", both);
+    const after = integerFlag(args, "after", both);
+    const paths = listFlag(args, "path");
+    const excludes = listFlag(args, "exclude");
+    const languages = listFlag(args, "lang");
+    const repositories = listFlag(args, "repo");
+    const refs = refIdsOverride === undefined ? listFlag(args, "ref") : uniqueSortedByCodepoints(refIdsOverride);
+    const maxMatches = numberFlag(args, "max-matches");
+    const maxPerFile = numberFlag(args, "max-per-file");
+    const maxScanned = numberFlag(args, "max-scanned");
+    return {
+        pattern,
+        regex: boolFlag(args, "regex"),
+        // grep ist per Vorgabe gross-/kleinschreibungsempfindlich, wie das Werkzeug,
+        // dessen Namen der Modus traegt. `-i` hebt das auf.
+        caseSensitive: !boolFlag(args, "ignore-case"),
+        wholeWord: boolFlag(args, "word"),
+        workspaceId,
+        ...(repositories.length === 0 ? {} : { repositories }),
+        ...(refs.length === 0 ? {} : { refs }),
+        ...(languages.length === 0 ? {} : { languages }),
+        ...(paths.length === 0 ? {} : { pathGlob: paths }),
+        ...(excludes.length === 0 ? {} : { pathExclude: excludes }),
+        contextLinesBefore: before,
+        contextLinesAfter: after,
+        ...(maxMatches === undefined ? {} : { maxMatches }),
+        ...(maxPerFile === undefined ? {} : { maxMatchesPerFile: maxPerFile }),
+        ...(maxScanned === undefined ? {} : { maxScannedChunks: maxScanned }),
+        sort: enumFlag(args, "grep-sort", GREP_SORTS, "path"),
+    };
+}
+/* --------------------------------------------------------------------- */
+export function renderSearch(ctx, set, format, explain) {
+    if (format !== "text") {
+        // WP-230: `line` und nicht `out`. Die Formatierer liefern ihren Text OHNE
+        // abschliessenden Zeilenumbruch; ohne ihn klebte der Ledger-Hinweis an der
+        // letzten Ausgabezeile, und bei `jsonl` haette die letzte Zeile keinen
+        // Abschluss — beides macht eine maschinenlesbare Ausgabe unlesbar.
+        line(ctx.io, formatSearchResultSet(set, format));
+        reportLedger(ctx, set.skipped.length, set.warnings.length);
+        return;
+    }
+    // Die Enthaltung wird VOR dem Leer-Zweig bestimmt und unabhaengig von ihm
+    // gemeldet. Frueher stand sie ausschliesslich in `if (totalHits === 0)` —
+    // eine Enthaltung wurde also aus der Listenlaenge erschlossen. Sobald
+    // Treffer trotz Ablehnung stehenbleiben, haette dieser Zweig geschwiegen und
+    // eine selbstbewusst aussehende Trefferliste gedruckt.
+    const insufficient = set.warnings.some((warning) => warning.code === NO_SUFFICIENT_MATCH_WARNING_CODE);
+    if (set.totalHits === 0) {
+        note(ctx.io, failedTargets(set.skipped).length > 0
+            ? "No results, but the search was also incomplete (see below)."
+            : insufficient
+                ? "No sufficiently relevant results found."
+                : "No results.");
+        reportLedger(ctx, set.skipped.length, set.warnings.length);
+        if (set.skipped.length > 0) {
+            note(ctx.io, "Skipped candidates appear in the --format=json skip ledger.");
+        }
+        return;
+    }
+    if (insufficient) {
+        note(ctx.io, "No sufficiently relevant results found.");
+    }
+    for (const group of set.groups) {
+        if (set.profileSeparation) {
+            note(ctx.io, `# Profile ${group.embeddingProfileId} (${group.repoIds.join(", ")})`);
+        }
+        // Vorbehalte unbedingt drucken. Sie standen bisher NUR unter
+        // `profileSeparation`, und das ist im ausgelieferten CLI nie wahr:
+        // `wireSearchEngine` baut genau ein Profilziel. Der Vorbehalt traegt die
+        // drei gemessenen Werte samt Schwellen — er war damit im Textmodus
+        // unsichtbar.
+        for (const caveat of group.caveats)
+            note(ctx.io, `# Qualification: ${caveat}`);
+        for (const hit of group.hits) {
+            if (explain) {
+                // WP-230: `formatHitAsText` endet ohne Zeilenumbruch. Mit `out` klebte
+                // der naechste Treffer — und am Ende der Ledger-Hinweis — an der
+                // letzten Zeile der Score-Zerlegung.
+                line(ctx.io, formatHitAsText(hit));
+            }
+            else {
+                line(ctx.io, compactHitLine(hit));
+            }
+        }
+    }
+    reportLedger(ctx, set.skipped.length, set.warnings.length);
+}
+/** Eine Zeile je Treffer — Rang, Ort, Symbol, Score. */
+function compactHitLine(hit) {
+    const where = `${hit.filePath}:${String(hit.range.startLine)}-${String(hit.range.endLine)}`;
+    const symbol = hit.symbolName === undefined ? "" : `  ${hit.symbolName}`;
+    const incomplete = hit.incompletePayloadFields === undefined || hit.incompletePayloadFields.length === 0
+        ? ""
+        : `  [Fallback values: ${[...hit.incompletePayloadFields].sort(compareCodepoints).join(",")}]`;
+    const lines = [
+        `${String(hit.rank).padStart(3)}  ${hit.score.final.toFixed(4)}  ${where}${symbol}${incomplete}`,
+    ];
+    if (hit.graphContext !== undefined) {
+        lines.push(...formatSearchGraphRelationsAsText("context", hit.graphContext));
+    }
+    if (hit.linkedSymbols !== undefined) {
+        lines.push(...formatSearchGraphRelationsAsText("linked", hit.linkedSymbols));
+    }
+    return lines.join("\n");
+}
+export function renderGrep(ctx, set, format) {
+    if (format !== "text") {
+        // WP-230, dieselbe Ursache wie oben.
+        line(ctx.io, formatGrepResultSet(set, format));
+        reportGrepTail(ctx, set);
+        return;
+    }
+    for (const match of set.matches) {
+        for (const before of match.before) {
+            line(ctx.io, `${match.filePath}-${String(before.line)}-${before.text}`);
+        }
+        line(ctx.io, `${match.filePath}:${String(match.line)}:${String(match.column)}:${match.lineText}`);
+        for (const after of match.after) {
+            line(ctx.io, `${match.filePath}-${String(after.line)}-${after.text}`);
+        }
+    }
+    reportGrepTail(ctx, set);
+}
+function reportGrepTail(ctx, set) {
+    note(ctx.io, `${String(set.totalMatches)} results, ${String(set.scannedChunks)} chunks searched.`);
+    if (set.truncated) {
+        note(ctx.io, `Truncated; reason: ${set.truncationReason ?? "unbenannt"}.`);
+    }
+    reportLedger(ctx, set.skipped.length, set.warnings.length);
+}
+/**
+ * Der Ledger-Hinweis. Er steht auf stderr, weil er Diagnose ist — aber er
+ * steht IMMER, wenn es etwas zu melden gibt. Ein Ledger, den niemand sieht,
+ * ist kein Ledger.
+ */
+function reportLedger(ctx, skipped, warnings) {
+    if (skipped === 0 && warnings === 0)
+        return;
+    note(ctx.io, `Note: ${String(skipped)} skipped candidates, ${String(warnings)} warning(s). ` +
+        "Both are fully available in --format=json.");
+}
+export function toRuntimeError(outcome, qdrantUrl, timeoutMs, request, useOffline) {
+    const backendLabel = qdrantUrl.startsWith("file:") ? "LanceDB" : "Qdrant";
+    if (outcome.timedOut) {
+        const mode = request === "grep" ? "grep" : (request.mode ?? "hybrid");
+        const usesEmbedding = mode === "semantic" || mode === "hybrid";
+        const stages = [`Search retrieval from ${backendLabel} at ${qdrantUrl}`];
+        if (usesEmbedding)
+            stages.push(useOffline ? "local query embedding" : "Query embedding through Ollama");
+        const graphFlags = [];
+        if (request !== "grep" && request.includeContext)
+            graphFlags.push("--context");
+        if (request !== "grep" && request.includeLinked)
+            graphFlags.push("--linked");
+        if (graphFlags.length > 0)
+            stages.push(`Graph enrichment (${graphFlags.join(" ")}) from ${backendLabel}`);
+        return new EnvironmentError(`The query was cancelled after ${String(timeoutMs)}ms; no result is available. ` +
+            `Mode "${mode}" covers ${stages.join("; ")}.`, `Run \`untangle doctor\` to check ${backendLabel}${usesEmbedding && !useOffline ? " and Ollama" : ""} with separate deadlines.` +
+            (graphFlags.length > 0
+                ? " Compare the runtime with the same query without graph enrichment."
+                : ""), { cause: outcome.error });
+    }
+    const error = outcome.error;
+    const message = errorMessage(error);
+    if ((isUntangleError(error) &&
+        (error.code === "QDRANT_UNAVAILABLE" ||
+            error.code === "LANCEDB_UNAVAILABLE" ||
+            error.code === "LANCEDB_SCHEMA_INCOMPATIBLE")) ||
+        /QDRANT_UNAVAILABLE|LANCEDB_UNAVAILABLE|fetch failed|ECONNREFUSED|ENOTFOUND|timed out/iu.test(message)) {
+        return new EnvironmentError(`The store at ${qdrantUrl} did not answer the query: ${message}`, `Run \`untangle doctor\` to check ${backendLabel} and Ollama independently.`, { cause: error });
+    }
+    if (/EMBEDDING|OLLAMA|model/iu.test(message)) {
+        return new EnvironmentError(`Could not create the query embedding: ${message}`, "Run `untangle doctor` to check whether Ollama is running and has the model.", { cause: error });
+    }
+    return new OperationalError(`Search failed: ${message}`, undefined, {
+        cause: error,
+    });
+}
+//# sourceMappingURL=query.js.map