@opengeni/jev 0.1.0-canary.36199476632001

package/dist/code-search/config.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Every code_search threshold, budget and cap in one place. The defaults are scout-0.3.1's Jev
+ * configuration, tuned on the E1 DEV split (2026-09-24); change them only with a new evaluation.
+ */
+export interface CodeSearchConfig {
+    recall: {
+        /** Candidate files passed to wave 1. */
+        maxCandidates: number;
+        /** Matching lines kept per file per keyword. */
+        maxMatchesPerFile: number;
+        /** rg --max-filesize (bytes); also the read cap for candidate files. */
+        maxFileBytes: number;
+        /** rg --max-columns: lines longer than this (minified / generated / data blobs) are ignored entirely. */
+        maxLineColumns: number;
+        /** Multiplier for test files unless the question is about tests. */
+        testWeight: number;
+        /** Path-name match bonus as a fraction of the keyword's IDF. */
+        pathBonus: number;
+        /** Extra weight per log(1 + matching lines) (tie breaker). */
+        hitCountWeight: number;
+        /** Single plain words up to this length are searched with a leading word boundary (`\bturn`, not `return`). */
+        shortWordMaxLen: number;
+        /** Compound keywords with zero hits retry their 2-part fragments (e.g. shouldCompactContext -> compactContext). */
+        fragmentFallback: boolean;
+        /** If paths restrict the search and fewer candidates than this are found, widen to the whole workspace. */
+        minCandidatesBeforeWiden: number;
+        /** Extra rg exclude globs (on top of the built-in list). */
+        extraExcludes: string[];
+        /** Also search hidden files/dirs (.github/workflows, .env.example, .changeset); .git is always excluded. */
+        searchHidden: boolean;
+        /** Multiplier for release notes (CHANGELOG*, .changeset/) unless the question is about history/releases. */
+        changelogWeight: number;
+        /** Time limit per ripgrep call; a timed-out search continues with partial output. */
+        ripgrepTimeoutMs: number;
+    };
+    wave1: {
+        filesPerRequest: number;
+        hitLinesPerFile: number;
+        hitLineChars: number;
+        /** Hard cap on files selected for windowing. */
+        maxFiles: number;
+        /** Always take at least this many files by judge score (guards against an over-strict T1). */
+        minFiles: number;
+        /** Always keep the top-N lexical files (fusion guard against judge misses). */
+        lexicalGuard: number;
+    };
+    wave2: {
+        windowsPerFile: number;
+        /** How many of a file's strongest hit lines seed windows (before merging/splitting). */
+        seedHitsPerFile: number;
+        /** Max lines to walk up from a hit looking for the enclosing declaration. */
+        maxUp: number;
+        /** Max lines below a hit kept in its window. */
+        maxDown: number;
+        /** Windows longer than this are split around hit clusters. */
+        maxWindowLines: number;
+        /** Fallback context when no enclosing declaration is found within maxUp. */
+        fallbackBefore: number;
+        fallbackAfter: number;
+        /** Merge windows whose gap is at most this many lines. */
+        mergeGap: number;
+        /** Windows shorter than this get surrounding context. */
+        minWindowLines: number;
+        passagesPerRequest: number;
+        /** Max passage text chars per Jev request. */
+        maxRequestChars: number;
+        /** Max passages verified in wave 2. */
+        maxPassages: number;
+        /** Code lines longer than this are cut with an explicit marker. */
+        maxLineChars: number;
+        /** Same for prose files (md/mdx/txt/rst), which often have single-line paragraphs of 1-6k chars. */
+        maxProseLineChars: number;
+        /** Windows whose rendered text is longer are split into whole-line sub-windows around their hits. */
+        maxWindowChars: number;
+        /** Same for markdown (sections are long, paragraphs independent). */
+        maxProseWindowChars: number;
+    };
+    wave3: {
+        enabled: boolean;
+        maxLeadCandidates: number;
+        maxLeadsFollowed: number;
+        /** Leads are extracted from at most this many of the most relevant passages (all >= T2). */
+        seedPassages: number;
+        defsPerLead: number;
+    };
+    status: {
+        enabled: boolean;
+        /** Max evidence chars sent to the status check (best passages first); keeps the request under Jev's 32k-token limit. */
+        maxEvidenceChars: number;
+        /** sufficient: overall >= hi and every sub-question >= hi. */
+        hi: number;
+        /** partial: overall >= lo or any sub-question >= hi. */
+        lo: number;
+    };
+    pack: {
+        charsPerToken: number;
+        /** Include passages below T2 only if fewer than this many passed (top by score, above minRelevance). */
+        minPassages: number;
+        minRelevance: number;
+        /** Fill the remaining budget with passages below T2 (ranked). */
+        fillBudget: boolean;
+        moreCandidates: number;
+        leadsNotFollowed: number;
+        /** A trimmed passage must keep at least this many lines. */
+        minTrimLines: number;
+        /** File-diversity penalty: a second passage of one file must beat the first passage of another by this margin. */
+        filePenalty: number;
+        /** Passages whose rendered block is longer are trimmed around their hits to this many chars (0 = off). */
+        maxPassageChars: number;
+        /** Multiplier on the rel used for pack ORDERING of release-note passages; 1 = off. */
+        changelogPrior: number;
+        /** Same for prose docs (md/mdx/txt/rst, not release notes); 1 = off. */
+        docPrior: number;
+        /** Same for test files unless the question is about tests; 1 = off. */
+        testPrior: number;
+        /** Pack ordering score = (rel + lexWeight x lexical passage score) x prior. */
+        lexWeight: number;
+    };
+    jev: {
+        /** Inline the question text in every Jev question when it is at most this long; else reference `question`. */
+        inlineQuestionMaxChars: number;
+        /** Wave 1: put the true/false rubric on every file question instead of once in the state. */
+        fileCriteriaPerQuestion: boolean;
+        /** Keep-alive connections opened while recall runs (0 = off). */
+        warmConnections: number;
+    };
+    thresholds: {
+        /** Wave 1: file triage floor (p >= T1 selects, up to maxFiles). */
+        T1: number;
+        /** Wave 2: passage relevance floor for inclusion in the pack, lead seeding and sub-question coverage. */
+        T2: number;
+        /** Wave 3: lead floor (p >= T3 is followed, up to maxLeadsFollowed). */
+        T3: number;
+    };
+}
+export type CodeSearchConfigOverride = {
+    [K in keyof CodeSearchConfig]?: Partial<CodeSearchConfig[K]>;
+};
+export declare const DEFAULT_CODE_SEARCH_CONFIG: Readonly<CodeSearchConfig>;
+/** Defaults with a partial override merged on top (unknown keys and wrong types are rejected), validated. */
+export declare function codeSearchConfig(override?: CodeSearchConfigOverride): CodeSearchConfig;
+export declare function validateCodeSearchConfig(c: CodeSearchConfig): void;

package/dist/code-search/judge.d.ts

@@ -0,0 +1,169 @@
+/**
+ * judge.ts - the only place where scores come from: Jev answers one probability per judged item.
+ *
+ * All Jev wording lives in PROMPTS below (one place to review). Design rules followed:
+ *  - one state + many narrow Nouls per request (fan-out); one Noul per candidate (multi-select)
+ *  - criteria text is explicit (in the state for 60-file triage batches, per question for passages)
+ *  - the literal question text is inlined in every question (no `collections[i]`-style indirection)
+ *  - state holds only the candidates being judged (filtered by code first)
+ *  - no counting, math or dates asked of Jev; code combines answers
+ * A Jev failure is not replaced by lexical scores: it propagates and the whole search fails.
+ */
+import { type JevClient, type JevNoulQuestion } from "../client.js";
+import type { CodeSearchConfig } from "./config.js";
+export interface JudgeContext {
+    question: string;
+    subQuestions: string[];
+}
+export interface FileItem {
+    id: string;
+    path: string;
+    /** path + best hit lines, as shown to the judge */
+    descriptor: string;
+    /** Normalized lexical score; used only if Jev returns no usable number for this item. */
+    lex: number;
+}
+export interface PassageItem {
+    id: string;
+    path: string;
+    start: number;
+    end: number;
+    /** rendered `N| text` */
+    text: string;
+    label?: string | undefined;
+    lex: number;
+    lexCov: number[];
+}
+export interface LeadItem {
+    id: string;
+    name: string;
+    seenAt: string;
+    context: string;
+    lex: number;
+}
+export interface PassageScore {
+    rel: number;
+    cov: number[];
+}
+export interface StatusScore {
+    overall: number;
+    subs: number[];
+}
+export interface StageStats {
+    requests: number;
+    inputTokens: number;
+    costUsd: number;
+    ms: number;
+}
+export type JudgeEvent = (stage: string, data: Record<string, unknown>) => void;
+export declare const PROMPTS: {
+    fileTask: string;
+    fileCriteria: {
+        yes: string;
+        no: string;
+    };
+    fileQuestion: (id: string, path: string, q: string) => string;
+    fileQuestionPerQ: (id: string, path: string, q: string) => string;
+    passageTask: string;
+    passageQuestion: (id: string, path: string, a: number, b: number, q: string) => string;
+    passageCriteria: {
+        true: string;
+        false: string;
+    };
+    coverageQuestion: (id: string, path: string, a: number, b: number, sub: string) => string;
+    coverageCriteria: {
+        true: string;
+        false: string;
+    };
+    leadTask: string;
+    leadCriteria: {
+        yes: string;
+        no: string;
+    };
+    leadQuestion: (id: string, name: string, q: string) => string;
+    statusTask: string;
+    statusQuestion: (q: string) => string;
+    statusSubQuestion: (sub: string) => string;
+    statusCriteria: {
+        true: string;
+        false: string;
+    };
+};
+export declare function buildFileRequest(items: FileItem[], ctx: JudgeContext, cfg: CodeSearchConfig): {
+    state: {
+        task: string;
+        question: string;
+        criteria?: {
+            yes: string;
+            no: string;
+        };
+        files: {
+            [k: string]: string;
+        };
+    };
+    questions: Record<string, JevNoulQuestion>;
+};
+export declare function buildPassageRequest(items: PassageItem[], ctx: JudgeContext, cfg: CodeSearchConfig): {
+    state: {
+        task: string;
+        question: string;
+        passages: {
+            [k: string]: {
+                file: string;
+                lines: string;
+                in?: string;
+                text: string;
+            };
+        };
+    };
+    questions: Record<string, JevNoulQuestion>;
+};
+export declare function buildLeadRequest(items: LeadItem[], ctx: JudgeContext, cfg: CodeSearchConfig): {
+    state: {
+        task: string;
+        question: string;
+        criteria: {
+            yes: string;
+            no: string;
+        };
+        leads: {
+            [k: string]: string;
+        };
+    };
+    questions: Record<string, JevNoulQuestion>;
+};
+export declare function buildStatusRequest(evidence: string, ctx: JudgeContext, cfg: CodeSearchConfig): {
+    state: {
+        task: string;
+        question: string;
+        evidence: string;
+    };
+    questions: Record<string, JevNoulQuestion>;
+};
+/** Group passages into requests: consecutive (same-file first) up to perRequest items and maxChars of text. */
+export declare function chunkPassages(items: PassageItem[], perRequest: number, maxChars: number): PassageItem[][];
+/** Split into the fewest groups of at most n items, as equal in size as possible (69 -> 35 + 34, not 60 + 9). */
+export declare function chunkEven<T>(xs: T[], n: number): T[][];
+export declare class JevJudge {
+    private readonly o;
+    private readonly stageStats;
+    private jevModel;
+    constructor(o: {
+        client: JevClient;
+        config: CodeSearchConfig;
+        signal: AbortSignal;
+        onEvent?: JudgeEvent | undefined;
+    });
+    stats(): Record<string, StageStats>;
+    model(): string | null;
+    private stat;
+    /** One logical request (the client may split its questions into several HTTP requests). */
+    private ask;
+    /** Run a stage's batches in parallel; the first failure rejects the stage. */
+    private stage;
+    scoreFiles(items: FileItem[], ctx: JudgeContext): Promise<Map<string, number>>;
+    scorePassages(items: PassageItem[], ctx: JudgeContext, stage?: string): Promise<Map<string, PassageScore>>;
+    scoreLeads(items: LeadItem[], ctx: JudgeContext): Promise<Map<string, number>>;
+    /** null = nothing to check (empty evidence). */
+    status(evidence: string, ctx: JudgeContext): Promise<StatusScore | null>;
+}

package/dist/code-search/leads.d.ts

@@ -0,0 +1,96 @@
+/**
+ * leads.ts - wave 3: identifiers referenced by relevant passages whose definitions were not read.
+ *
+ * Extraction (code only): called functions, imported names, PascalCase types, UPPER_CASE constants,
+ * env/config keys and camelCase member accesses. Excluded: names already searched (keywords and their
+ * variants), names defined inside the selected passages, a stoplist of builtins/common helpers, and
+ * names shorter than 4 chars. Definitions are located with one ripgrep regex call (a few when the names do
+ * not fit one pattern under CODE_SEARCH_MAX_PATTERN_CHARS).
+ */
+import type { CodeSearchConfig } from "./config.js";
+import { type WorkspaceSession } from "./session.js";
+export interface SeedPassage {
+    path: string;
+    start: number;
+    /** raw file lines of the passage (no `N|` prefixes) */
+    lines: string[];
+    rel: number;
+}
+export interface LeadCandidate {
+    name: string;
+    /** weighted frequency: sum of relevance of seed passages mentioning it + occurrence bonus */
+    weight: number;
+    occurrences: number;
+    called: boolean;
+    seenAt: {
+        path: string;
+        line: number;
+    };
+    context: string;
+    kinds: string[];
+}
+export declare const LEAD_STOPLIST: Set<string>;
+/** Names declared inside a passage (so they are not leads). */
+export declare function definedNames(text: string): Set<string>;
+/** Raw identifier occurrences (name, kind) in one line. */
+export declare function identifiersInLine(line: string): Array<{
+    name: string;
+    kind: string;
+}>;
+/**
+ * Extract lead candidates from seed passages (most relevant first), ranked by weighted frequency.
+ * `searched` = lowercased keywords + variants (already searched; not leads).
+ */
+export declare function extractLeads(seeds: SeedPassage[], searched: Set<string>, questionWords: Set<string>, max: number): LeadCandidate[];
+export interface DefinitionHit {
+    name: string;
+    path: string;
+    line: number;
+    kind: "decl" | "sqlfn" | "method" | "key";
+    text: string;
+}
+/** The JS regexes used to classify an rg match line for one name (priority order). */
+export declare function definitionKinds(name: string): Array<{
+    kind: DefinitionHit["kind"];
+    re: RegExp;
+}>;
+/**
+ * rg pattern (ASCII mode) for definition-shaped lines of any of the names: declarations, SQL functions,
+ * methods and object keys / fields / config keys. Classified per name in JS with definitionKinds().
+ */
+export declare function definitionPattern(names: readonly string[]): string;
+/**
+ * definitionPattern over consecutive groups of names, each pattern at most maxChars. A name whose own pattern
+ * is longer is left out: it gets no definition, as after a failed search.
+ */
+export declare function definitionPatterns(names: readonly string[], maxChars?: number): string[];
+/** Package root of a path: the first two segments for apps/ and packages/ (apps/worker, packages/runtime), else the first. */
+export declare function packageOf(path: string): string;
+/**
+ * Choose the best definitions per name. A name can be defined in many places (`search`, `isRecord`), so locality
+ * dominates: the file where the lead was seen, then its package; then kind rank (declaration > method > key),
+ * non-test, an already-selected file, a config-ish path for keys, path, line.
+ */
+export declare function chooseDefinitions(hits: DefinitionHit[], preferPaths: Set<string>, perName: number, allowTests?: boolean, seenAt?: Map<string, string>): Map<string, DefinitionHit[]>;
+export interface DefinitionSearch {
+    hits: DefinitionHit[];
+    /** name -> number of repository files that mention it as a word (for an IDF-style genericity penalty) */
+    fileCounts: Map<string, number>;
+    ms: number;
+}
+/** Files a definition search never needs: prose/data (definitions of code identifiers live in code or SQL). */
+export declare const DEF_SCAN_EXCLUDES: string[];
+/** Test files, excluded from the definition scan unless the question is about tests. */
+export declare const TEST_EXCLUDES: string[];
+/**
+ * ONE rg pass (ASCII-mode regex, full lines) for definition-shaped lines of all names over code and SQL files
+ * (tests only when the question is about tests), classified per name in JS: declarations/SQL functions/methods
+ * first; object keys / fields / config keys (`name:` / `name =`) only for names without a stronger definition,
+ * and a name whose only definitions are more than maxKeyOnlyDefs keys is a generic field (sessionId, accountId)
+ * and gets none. fileCounts = files with any definition-shaped line for the name (generic fields and helpers
+ * redefined everywhere score high), used as a genericity penalty. About 0.4 CPU-s on a 6k-file repository; a
+ * second pass that counted every mention cost another ~0.7 CPU-s and full-line mention output was 80k lines.
+ * Names that do not fit one pattern under the cap are searched in a few passes, merged line by line.
+ * A failed definition search yields no hits (the leads are then dropped), as in scout.
+ */
+export declare function locateDefinitions(session: WorkspaceSession, names: string[], cfg: CodeSearchConfig, excludeArgs: string[], maxKeyOnlyDefs?: number, allowTests?: boolean): Promise<DefinitionSearch>;

package/dist/code-search/pack.d.ts

@@ -0,0 +1,106 @@
+/**
+ * pack.ts - bounded evidence pack.
+ *
+ * Priority: (1) for each sub-question, the best passage covering it (coverage >= T2), (2) passages with
+ * relevance >= T2 by relevance, (3) if fewer than minPassages passed, the next best above minRelevance,
+ * (4) optionally (fillBudget) the rest. Greedy under a char budget (tokens * charsPerToken); a passage that
+ * does not fit is trimmed to whole lines around its hits (>= minTrimLines) and marked, never cut mid-line.
+ * Output groups passages by file (files by best relevance, passages by line).
+ */
+import type { CodeSearchConfig } from "./config.js";
+import { type RenderOpts } from "./windows.js";
+export interface EvidencePassage {
+    id: string;
+    path: string;
+    start: number;
+    end: number;
+    fileLines: string[];
+    hits: number[];
+    label?: {
+        line: number;
+        text: string;
+    } | undefined;
+    kind: "hit" | "header" | "def";
+    rel: number;
+    cov: number[];
+    /** Lexical passage score (used by pack.lexWeight). */
+    lex?: number | undefined;
+    lead?: string | undefined;
+    /** How lines are rendered (line cap + needles for cutting very long lines around a hit). */
+    render?: RenderOpts | undefined;
+}
+export interface PackedPassage {
+    id: string;
+    path: string;
+    start: number;
+    end: number;
+    origStart: number;
+    origEnd: number;
+    trimmed: boolean;
+    rel: number;
+    cov: number[];
+    kind: EvidencePassage["kind"];
+    lead?: string | undefined;
+    label?: {
+        line: number;
+        text: string;
+    } | undefined;
+    /** rendered block including its `==` header line */
+    block: string;
+}
+export interface PackOptions {
+    subQuestions: string[];
+    T2: number;
+    /** Chars available for passage blocks (header/footer excluded). */
+    bodyChars: number;
+    cfg: CodeSearchConfig;
+    /** Apply pack.changelogPrior (false when the question is about history / releases). */
+    downweightChangelogs?: boolean;
+    /** Apply pack.testPrior (false when the question is about tests). */
+    downweightTests?: boolean;
+}
+export interface PackBody {
+    included: PackedPassage[];
+    excluded: EvidencePassage[];
+    body: string;
+    priority: string[];
+}
+/**
+ * Greedy file-diverse order: repeatedly take the passage with the highest eff(x) - penalty x (passages already
+ * taken from its file). penalty 0 = plain descending eff.
+ */
+export declare function diverseOrder(xs: EvidencePassage[], eff: (x: EvidencePassage) => number, penalty: number, taken: Map<string, number>): EvidencePassage[];
+/** Path prior for pack ordering (release notes, prose docs, tests); 1 for code. */
+export declare function pathPrior(path: string, o: Pick<PackOptions, "cfg" | "downweightChangelogs" | "downweightTests">): number;
+/** Pack ordering score: (rel + lexWeight x lex) x path prior. Inclusion floors (T2, minRelevance) still use raw rel. */
+export declare function packScore(x: EvidencePassage, o: Pick<PackOptions, "cfg" | "downweightChangelogs" | "downweightTests">): number;
+export declare function priorityOrder(passages: EvidencePassage[], o: Pick<PackOptions, "subQuestions" | "T2" | "cfg" | "downweightChangelogs" | "downweightTests">): EvidencePassage[];
+export declare function renderBlock(x: EvidencePassage, start: number, end: number, o: PackOptions): string;
+/** Largest contiguous whole-line sub-range around the passage's hits whose block fits in maxChars. */
+export declare function trimToFit(x: EvidencePassage, maxChars: number, o: PackOptions): {
+    start: number;
+    end: number;
+} | null;
+export declare function packBody(passages: EvidencePassage[], o: PackOptions): PackBody;
+export interface FooterInput {
+    excluded: EvidencePassage[];
+    otherFiles: Array<{
+        path: string;
+        score: number;
+    }>;
+    leadsNotFollowed: Array<{
+        name: string;
+        score: number;
+        seenAt: string;
+        note?: string;
+    }>;
+    zeroHitKeywords: Array<{
+        raw: string;
+        fragments: string[];
+    }>;
+    widenedNote?: string;
+    cfg: CodeSearchConfig;
+    maxChars: number;
+}
+/** Footer lines, dropping list entries from the end until it fits maxChars. */
+export declare function renderFooter(f: FooterInput): string;

package/dist/code-search/recall.d.ts

@@ -0,0 +1,155 @@
+/**
+ * recall.ts - wide, deterministic lexical recall with ripgrep.
+ *
+ * One ripgrep pass over the union of every keyword's identifier variants, searched case-insensitively
+ * (camelCase <-> snake_case <-> kebab <-> spaced phrase; SCREAMING and Pascal forms are covered by -i);
+ * a union longer than CODE_SEARCH_MAX_PATTERN_CHARS is split into several passes and merged. Lines are
+ * attributed to keywords in JS. Short plain words get a leading word boundary so `turn` does not
+ * match `return`. Per-file score = sum over DISTINCT matched keywords of IDF + path bonus + a small
+ * hit-count tie breaker; tests are down-weighted unless the question is about tests.
+ */
+import type { CodeSearchConfig } from "./config.js";
+import { type WorkspaceSession } from "./session.js";
+export declare const BUILTIN_EXCLUDES: string[];
+export interface KeywordInfo {
+    index: number;
+    raw: string;
+    variants: string[];
+    /** "phrase" = any variant as a substring; "word-prefix" = `\bword`. */
+    mode: "phrase" | "word-prefix";
+    /** JS-dialect pattern (attribution, window scoring, line cutting). */
+    pattern: string;
+    /** ripgrep-dialect pattern: same language, but word boundaries are ASCII `(?-u:\b)`. */
+    rgPattern: string;
+    /** Number of files with at least one matching line (content). */
+    df: number;
+    /** Files whose path matches (no content needed). */
+    pathDf: number;
+    hitLines: number;
+    idf: number;
+    /** Fragments used because the full keyword had zero hits. */
+    fragments: string[];
+}
+export interface HitLine {
+    line: number;
+    text: string;
+    kws: number[];
+}
+export interface FileCandidate {
+    path: string;
+    lexScore: number;
+    /** keyword index -> matching line count */
+    kwHits: Record<number, number>;
+    pathKws: number[];
+    hitLines: Map<number, HitLine>;
+    isTest: boolean;
+    isDoc: boolean;
+}
+export interface RecallResult {
+    keywords: KeywordInfo[];
+    totalFiles: number;
+    candidates: FileCandidate[];
+    scoredFiles: number;
+    searchPaths: string[];
+    widened: boolean;
+    /** Path prefixes that do not exist in the workspace (or are not workspace-relative); ignored. */
+    missingPrefixes: string[];
+    /** The path prefixes that exist, workspace-relative. */
+    validPrefixes: string[];
+    /** Path-only candidates dropped because their content is binary (NUL in the first 8 KB). */
+    binaryDropped: number;
+    ms: number;
+}
+export interface RecallInput {
+    session: WorkspaceSession;
+    question: string;
+    keywords: string[];
+    pathPrefixes: string[];
+    config: CodeSearchConfig;
+}
+export declare function excludeArgs(cfg: CodeSearchConfig): string[];
+/** `--hidden` (rg skips dot-dirs such as .github/ by default); `.git/` stays excluded by BUILTIN_EXCLUDES. */
+export declare function hiddenArgs(cfg: CodeSearchConfig): string[];
+export declare function listFiles(session: WorkspaceSession, paths: string[], cfg: CodeSearchConfig): Promise<string[]>;
+/**
+ * Search pattern for one keyword. `pattern` is JS-dialect; `rgPattern` is the same for ripgrep except that the
+ * word boundary is ASCII: a Unicode `\b` under -i disables ripgrep's fast engines (measured on repo-snap: 5.6 s
+ * user CPU for one pass vs 0.2 s with `(?-u:\b)`), and JS `\b` is ASCII anyway.
+ */
+export declare function buildPattern(kw: string, cfg: CodeSearchConfig): {
+    pattern: string;
+    rgPattern: string;
+    mode: "phrase" | "word-prefix";
+    variants: string[];
+};
+/** Pattern for the 2-word fragments of a compound keyword (used only if the full keyword has zero hits). */
+export declare function fragmentPattern(frags: string[]): string;
+export interface RgMatch {
+    path: string;
+    line: number;
+    text: string;
+}
+/** Parse `rg --null --line-number --with-filename --no-heading` output. Omitted long lines are skipped. */
+export declare function parseRgOutput(out: string): RgMatch[];
+/**
+ * Whether a pattern built by this engine compiles: checked as a JS regex after mapping ripgrep's inline flag
+ * groups (`(?-u:`, `(?i:`) to plain groups. It tells an invalid pattern apart from ripgrep's exit 2 for an
+ * unreadable path.
+ */
+export declare function ripgrepPatternCompiles(pattern: string): boolean;
+/** One rg pass for a pattern (any number of alternatives), all matching lines, sorted by path then line. */
+export declare function searchPattern(session: WorkspaceSession, pattern: string, paths: string[], cfg: CodeSearchConfig, opts?: {
+    caseInsensitive?: boolean;
+    word?: boolean;
+    maxPerFile?: number;
+}): Promise<RgMatch[]>;
+/** Split a regex at its top-level `|` (outside groups, character classes and escapes). */
+export declare function splitAlternation(pattern: string): string[];
+/**
+ * Join alternatives with `|`, in order, into as few patterns of at most maxChars as possible. An alternative
+ * longer than maxChars on its own gets a pattern of its own.
+ */
+export declare function packAlternatives(alternatives: readonly string[], maxChars: number): string[];
+/** Matches of several searches, as one search over their union returns them: by path then line, each line once. */
+export declare function mergeMatches(lists: readonly RgMatch[][]): RgMatch[];
+/**
+ * The lines matching `(?:a)|(?:b)|...` over the alternatives. A union longer than maxPatternChars is split
+ * into several rg passes (an alternative too long on its own is split at its own top-level `|`), run a few
+ * at a time and merged, so the result is the same as one pass. A part that still does not fit (a keyword
+ * of thousands of characters) is not searched, so it reports zero hits.
+ */
+export declare function searchAlternatives(session: WorkspaceSession, alternatives: readonly string[], paths: string[], cfg: CodeSearchConfig, maxPatternChars?: number): Promise<RgMatch[]>;
+export declare function idfOf(df: number, n: number): number;
+/** Does the path mention the keyword (any variant, separators ignored)? */
+export declare function pathMatches(path: string, variants: string[]): boolean;
+/** JS regex for an rg pattern built by buildPattern/fragmentPattern (the escapes used are valid in both dialects). */
+export declare function jsRegex(pattern: string): RegExp | null;
+export interface Slot {
+    /** keyword index */
+    ki: number;
+    fragment: boolean;
+    re: RegExp | null;
+    literals: string[];
+}
+/**
+ * Attribute rg lines to keyword slots. Returns per slot the matches (all lines; the caller caps what it stores).
+ * A JS regex that fails to compile falls back to a case-insensitive literal test on the variants.
+ */
+export declare function attribute(matches: RgMatch[], slots: Slot[]): RgMatch[][];
+/**
+ * Normalize path prefixes to workspace-relative form ("./src/" -> "src"); prefixes that do not exist, are
+ * absolute or climb out with ".." are reported as missing instead of crashing ripgrep (exit 2, no output).
+ */
+export declare function normalizePrefixes(session: WorkspaceSession, prefixes: string[]): Promise<{
+    ok: string[];
+    missing: string[];
+}>;
+/** Workspace-relative form of a prefix, or null when it is absolute, climbs out, or starts with "-". */
+export declare function cleanPrefix(p: string): string | null;
+export declare function recall(input: RecallInput): Promise<RecallResult>;
+/** Weight of one hit line: sum of IDF of the distinct keywords on it. */
+export declare function lineWeight(h: HitLine, keywords: KeywordInfo[]): number;
+/** Up to n best hit lines of a file (by distinct-keyword IDF), returned in line order (long lines are trimmed by the caller). */
+export declare function bestHitLines(c: FileCandidate, keywords: KeywordInfo[], n: number): HitLine[];
+/** Words of all keywords (for overlap scoring). */
+export declare function keywordWords(keywords: KeywordInfo[]): Set<string>;