@octocodeai/octocode-tools-core 17.0.2 → 18.0.1

package/dist/oql/schemeText.d.ts

@@ -1,152 +0,0 @@
-export declare const OQL_SCHEMA_DOC: {
-    readonly schema: "oql";
-    readonly description: "octocode search — typed read-only queries over code, files, symbols, repos, packages, history, diffs, and graph evidence. Think source + answer type + filters + read/output options; use --explain for routing; follow next.* for pages, exact reads, materialization, or proof.";
-    readonly activeTargets: readonly import("./types.js").OqlActiveTarget[];
-    readonly reservedTargets: readonly import("./types.js").OqlReservedTarget[];
-    readonly sourceGuide: {
-        readonly local: "from:{kind:\"local\",path:\"./src\"}; shorthand: search \"term\" ./src, search ./src --tree, search file.ts --op documentSymbols. Best for local code/content/files/tree/LSP/diff.";
-        readonly github: "from:{kind:\"github\",repo:\"owner/repo\",ref?}; shorthand: search \"term\" owner/repo, search owner/repo --tree, search owner/repo#123 --target pullRequests. GitHub code is indexed/default-branch scoped; materialize for AST/LSP/local proof.";
-        readonly npm: "from:{kind:\"npm\"} with target:\"packages\"; shorthand: search zod --target packages. Use to resolve package metadata and source repo, then continue with GitHub or local/materialized proof.";
-        readonly materialized: "from:{kind:\"materialized\",localPath:\"/abs/path\"} after target:\"materialize\", clone, or cache fetch. Use when a remote repo/subtree must behave like local code.";
-    };
-    readonly plainLanguage: {
-        readonly source: "`from` = where to look: local path, GitHub repo, npm, or a materialized checkout.";
-        readonly answerType: "`target` = what kind of answer you want: code matches, file content, tree, files, symbols, repos, packages, PRs, commits, diffs, research packets, graph proof, or materialization.";
-        readonly filters: "`where` = match/filter conditions for code and file discovery only: text, regex, AST shape, file fields, and boolean combinations.";
-        readonly readOptions: "`fetch` = what to read once you know the file/tree: exact content, compact content, symbol outline, ranges, match slices, or tree depth.";
-        readonly targetOptions: "`params` = options that belong to one answer type, such as LSP operation, PR number, package name, research intent, or graph proof.";
-        readonly output: "`view`, `select`, and `controls` = response shape, projected fields, search tuning, and cost limits.";
-        readonly paging: "`page` + `itemsPerPage` page the target's primary result domain. For code search that may be matched files; per-file match paging uses `controls.search.matchPage` / `--match-page`.";
-    };
-    readonly targetDecisionTree: {
-        readonly 'find a string/pattern in code': "target:code (shorthand default for text/regex/--pattern/--rule; needs a where filter)";
-        readonly 'read or slice a known file': "target:content (file positional + --content-view, --start-line/--end-line, or --match-string)";
-        readonly 'see the file/dir layout': "target:structure (--tree)";
-        readonly 'find files by name/glob/ext/size/mtime': "target:files (--search path, --name/--ext/--size-greater/--modified-within)";
-        readonly 'symbol defs/refs/callers/hover': "target:semantics (--op …; local or materialized only)";
-        readonly 'search GitHub repos': "target:repositories (--stars/--lang/--topic)";
-        readonly 'resolve an npm package': "target:packages";
-        readonly 'PR list or deep-read': "target:pullRequests (owner/repo#N)";
-        readonly 'commit history': "target:commits (--since/--until)";
-        readonly 'a diff': "target:diff ({prNumber} for a PR patch, {baseRef,headRef,path} for two refs)";
-        readonly 'dead-code / reachability sweep': "target:research, then upgrade with target:graph proof:\"lsp\"";
-        readonly 'make a remote repo behave like local (AST/LSP/negation)': "target:materialize (or clone / cache fetch)";
-    };
-    readonly agentBestPractices: readonly ["Start with cheap orientation: --tree, --search path, --view discovery, or --content-view symbols.", "Then narrow and read exact evidence: --match-string, --start-line/--end-line, --char-offset/--char-length, or --content-view none.", "Use snippets as discovery only; make decisions from exact content, PR/commit metadata, or LSP/graph proof.", "For semantics, run documentSymbols first to get line anchors, then references/callers/hover with symbolName + lineHint.", "For GitHub zero rows / providerUnindexed, do NOT claim absence — follow evidenceSemantics.providerUnindexed (verify path with structure, then materialize a bounded path).", "Read evidence.answerReady, evidence.complete, diagnostics, pagination, and next.* before concluding."];
-    readonly quickStart: {
-        readonly 'text search (local)': "search \"functionName\" ./src";
-        readonly 'text search (GitHub)': "search \"functionName\" vercel/next.js";
-        readonly 'package lookup (npm)': "search zod --target packages";
-        readonly 'PR deep read (GitHub)': "search vercel/next.js#1 --target pullRequests --comments --patches";
-        readonly 'commit history (GitHub)': "search vercel/next.js/packages/next/src --target commits --since 2024-01-01T00:00:00Z";
-        readonly 'browse a tree (local dir or owner/repo)': "search ./src --tree   |   search vercel/next.js --tree";
-        readonly 'read a file (local or owner/repo/path)': "search ./src/index.ts   |   search vercel/next.js/packages/next/src/server/config.ts";
-        readonly 'read a remote file (exact)': "search vercel/next.js/README.md --content-view none";
-        readonly 'semantics (local/materialized)': "search ./src/index.ts --op documentSymbols   |   search ./src/index.ts --op references --symbol runCLI --line 42";
-        readonly 'PR diff (GitHub)': "search vercel/next.js#123 --target diff   |   search vercel/next.js --target diff --pr 123";
-        readonly 'two-ref / two-file diff': "search src/a.ts src/b.ts --target diff   |   search owner/repo --target diff --base-ref <sha> --head-ref <sha> --path <file>";
-        readonly 'structural AST (local \u2014 needs full node shape)': "search --pattern \"function $NAME($$$ARGS) { $$$BODY }\" ./src --lang ts";
-        readonly 'structural AST (GitHub \u2014 clones bounded subtree)': "search --pattern \"function $NAME($$$ARGS) { $$$BODY }\" vercel/next.js/packages/next/src --lang ts --materialize auto";
-        readonly 'GitHub index miss recovery': "search useState packages/next/src --repo vercel/next.js --materialize required   |   clone vercel/next.js/packages/next/src   |   cache fetch vercel/next.js packages/next/src --depth tree";
-        readonly 'dead-code triage (research)': "search --query '{\"schema\":\"oql\",\"target\":\"research\",\"from\":{\"kind\":\"local\",\"path\":\"./src\"},\"params\":{\"intent\":\"reachability\",\"facets\":[\"symbols\",\"files\"]},\"itemsPerPage\":1,\"page\":1}'";
-        readonly 'LSP-proven dead symbols (graph)': "search --query '{\"schema\":\"oql\",\"target\":\"graph\",\"from\":{\"kind\":\"local\",\"path\":\"./src\"},\"params\":{\"intent\":\"reachability\",\"facets\":[\"symbols\"],\"proof\":\"lsp\",\"proofLimit\":5,\"includePackets\":true},\"page\":1,\"itemsPerPage\":10}'";
-        readonly 'OQL full-schema reference': "search --scheme";
-        readonly 'routing explanation before running': "search --explain --query '{\"target\":\"code\",\"from\":{\"kind\":\"local\",\"path\":\"./src\"},\"where\":{\"kind\":\"text\",\"value\":\"term\"}}'";
-    };
-    readonly evidenceSemantics: {
-        readonly 'answerReady:true': "The envelope answers the query as asked. No required follow-up.";
-        readonly 'answerReady:false': "Normal, NOT a failure — the results above are valid; only answerReady:true means no follow-up is needed. Follow next.* for more pages, LSP proof, or content.";
-        readonly 'complete:false': "Pages/proof/slices may remain. Read diagnostics: non-blocking warnings can still leave usable rows, but deletion/absence claims need the requested scope plus the listed continuations.";
-        readonly 'kind:proof': "Backend evaluated the request exactly.";
-        readonly 'kind:partial': "Truncation, pagination, or residual checks remain.";
-        readonly 'kind:candidate': "Useful evidence, not proof. research/graph are always candidate — upgrade via next.semantic/search/fetch.";
-        readonly 'kind:unsupported': "OQL could not safely execute the requested semantics.";
-        readonly 'proofStatus:confirmed-by-lsp': "LSP refs=0 inside the bounded workspace. Inspect for deletion only after checking entrypoints, framework conventions, dynamic imports, package exports, and scripts.";
-        readonly 'proofStatus:conflicting-evidence': "LSP refs>0 — symbol IS retained; check retainedBy before acting.";
-        readonly 'proofStatus:needs-framework-graph': "Maybe an entrypoint (framework/export/dynamic import) — LSP alone can't prove reachability.";
-        readonly 'proofStatus:candidate': "Pre-proof state (no LSP run yet) — run the row's next.graph (proof:\"lsp\") to resolve it to confirmed-by-lsp / conflicting-evidence / needs-framework-graph.";
-        readonly partialParse: "Non-fatal structural-search warning. Some files were not parsed, often because a literal prefilter had no anchor; add a literal/rule or broaden proof before claiming absence.";
-        readonly providerUnindexed: "GitHub provider returned zero rows. This is NOT absence. Verify the path with structure, then use bounded local proof: search \"term\" path --repo owner/repo --materialize required, clone owner/repo[/path], or cache fetch owner/repo [path] --depth file|tree|clone.";
-    };
-    readonly semanticsGuide: {
-        readonly documentSymbols: "list a file's symbols to get line anchors first (run before references/callers/hover)";
-        readonly references: "all usages of a symbol across the workspace (often includes its declaration)";
-        readonly callers: "incoming calls to a function/method (call sites only) — narrower than references";
-        readonly hover: "type, signature, and docs at a symbol";
-    };
-    readonly query: {
-        readonly schema: "\"oql\" (inserted by normalization)";
-        readonly target: string;
-        readonly from: "{ kind:\"local\", path } | { kind:\"github\", repo?, owner?, ref? } | { kind:\"materialized\", localPath, source? } | { kind:\"npm\" } — local row.path is relative to from.path; the pre-filled next.fetch carries the resolved ABSOLUTE path, so follow it directly rather than re-joining paths yourself";
-        readonly scope: "{ path?, language?, include?, exclude?, excludeDir?, hidden?, noIgnore?, minDepth?, maxDepth? } — minDepth/maxDepth bound directory recursion depth (0-64)";
-        readonly where: "filters for code/files only: text | regex | structural | field | all | any | not. To read a matched file slice, use fetch.content.match. For PR/commit text narrowing, use that target params hint.";
-        readonly materialize: "{ mode:\"never\"|\"auto\"|\"required\", strategy?:\"file\"|\"tree\"|\"subtree\"|\"repo\", allowFullRepo?, forceRefresh? }";
-        readonly fetch: "{ content?: { contentView:\"none\"|\"standard\"|\"symbols\", fullContent?, match?:{text|regex,case?}, range?:{startLine?,endLine?,contextLines?}, charOffset?, charLength? }, tree?:{ maxDepth?, pattern?, includeSizes?, extensions?, filesOnly?, directoriesOnly?, sortBy?:\"name\"|\"size\"|\"time\"|\"extension\", reverse? } } — read options for known files/trees; fetch.content.fullContent:true returns the WHOLE file in one shot (lossless, no char-window paging); to read the region around a string, anchor with fetch.content.match (NOT a top-level where, which is code/files only)";
-        readonly params: "target options (validated by OQL for common fields and by the backing tool exhaustively) — see params hints below";
-        readonly select: "string[] projection of result/continuation fields";
-        readonly view: "discovery | paginated | detailed";
-        readonly controls: "{ search?: { countLinesPerFile?, countMatchesPerFile?, onlyMatching?, unique?, countUnique?, contextLines?, invertMatch?, matchWindow?, matchContentLength?, maxMatchesPerFile?, matchPage?, sort?:\"relevance\"|\"matchCount\"|\"path\"|\"modified\"|\"accessed\"|\"created\"|\"size\"|\"name\", sortReverse?, rankingProfile?, debugRanking? }, budget?: { maxFiles?, maxCandidates?, maxBytes?, maxMaterializedBytes?, maxPlanNodes?, maxBooleanExpansion?, timeoutMs? } } — output/cost controls; sort values \"size\"/\"name\" apply to target:\"files\" only (lowered to localFindFiles sortBy), the rest are code-search sorts";
-        readonly limit: "number — total result cap where supported. Prefer itemsPerPage for paged research/graph/file-history continuations.";
-        readonly page: "number — top-level page number for OQL windowing/continuations";
-        readonly itemsPerPage: "number — page size for the target primary result domain. For code search this may be matched files, not individual matches; per-file match paging uses controls.search.matchPage. Per-target params expose backing-tool sub-pages only (filePage/commentPage/commitPage, etc.).";
-        readonly explain: "boolean";
-    };
-    readonly params: {
-        readonly semantics: "{ type:\"definition\"|\"references\"|\"callers\"|\"callees\"|\"callHierarchy\"|\"hover\"|\"documentSymbols\"|\"typeDefinition\"|\"implementation\"|\"workspaceSymbol\"|\"supertypes\"|\"subtypes\"|\"diagnostic\", uri?, symbolName?, symbolKind?, lineHint?, orderHint?, depth?, contextLines?, includeDeclaration?, groupByFile?, workspaceRoot?, format? } — backing tool lspGetSemantics; contextLines adds call-flow snippets; symbolKind filters returned symbol rows after documentSymbols/workspaceSymbol";
-        readonly repositories: "{ keywords?: string[], topicsToSearch?: string[], language?, owner?, stars?, license?, sort?, archived?, limit?, page? } — backing tool ghSearchRepos; keywords/topicsToSearch are arrays even for one term";
-        readonly packages: "{ packageName?: string | keywords?: string[], mode?:\"lean\"|\"full\", page? } — backing tool npmSearch";
-        readonly pullRequests: "{ state?:\"open\"|\"closed\"|\"merged\", author?, label?, keywordsToSearch?, prNumber?, reviewMode?, filePage?, commentPage?, commitPage?, limit?, page?, matchString?, matchScope?:\"body\"|\"title\"|\"comments\"|\"reviews\"|\"all\", content? } — backing tool ghHistoryResearch; matchString filters fetched PR title/body/comments/reviews per matchScope (default body), not a search-index query — no match → zeroMatches";
-        readonly commits: "{ path?, branch?, since?, until?, includeDiff?, limit?, page?, filePage?, itemsPerPage?, matchString? } — backing tool ghHistoryResearch type:\"commits\"; matchString filters commit messages; repo/directory diffs page changed files per commit with filePage/itemsPerPage";
-        readonly diff: "{ prNumber, files? } (PR patch via ghHistoryResearch) | { baseRef, headRef, path } (direct two-ref file diff via ghGetFileContent + local line diff); neither shape -> invalidQuery repair";
-        readonly research: "{ goal?, intent?:\"general\"|\"reachability\"|\"dependencies\"|\"symbols\", facets?:(\"symbols\"|\"files\"|\"dependencies\"|\"relations\")[], mode?:\"plan\"|\"analyze\"|\"prove\", maxFiles? } — TWO-PHASE: page:1+itemsPerPage:1 → data.summary (full-scope counts) and may include a bounded first packet page; page:2+ → data.packets[] continuation pages (candidates w/ retainedBy edges + per-packet next.*). Always evidence:\"candidate\"/answerReady:false (normal). Follow the row's pre-filled next.graph (proof:\"lsp\", proofLimit-bounded) to upgrade a page to LSP-proven proofStatus.";
-        readonly graph: "{ goal?, intent?:\"general\"|\"reachability\"|\"dependencies\"|\"symbols\", facets?:(…)[], mode?:\"plan\"|\"analyze\"|\"prove\", maxFiles?, subject?, subjectKind?, relation?, verdict?, direction?:\"incoming\"|\"outgoing\"|\"both\", proof?:\"none\"|\"lsp\", proofLimit?, includePackets?, includeFacts?, includeEdges? } — UPGRADE PATH: run a research row's pre-filled next.graph directly. proof:\"lsp\" sets per-row proofStatus: \"confirmed-by-lsp\" (refs=0 in bounded workspace; still inspect entrypoints/exports before deletion), \"conflicting-evidence\" (refs>0 → retained, check retainedBy), \"needs-framework-graph\" (maybe an entrypoint). answerReady:false is normal — follow next.* for more pages/proof.";
-        readonly materialize: "(no params; no `where`) clone/cache a bounded corpus (from:{kind:\"github\",repo} + scope.path) and return a stable materialized checkpoint row (localPath/repoRoot/ref/cache/complete) with next.structure/next.files. Use after GitHub providerUnindexed; for CLI alternatives use clone owner/repo[/path] or cache fetch owner/repo [path] --depth file|tree|clone.";
-    };
-    readonly predicates: {
-        readonly text: "{ kind:\"text\", value, case?, wholeWord? }";
-        readonly regex: "{ kind:\"regex\", value, dialect?:\"rust\"|\"pcre2\"|\"provider\", case?, wholeWord?, multiline?, dotAll? }";
-        readonly structural: "{ kind:\"structural\", lang, pattern? | rule? } (exactly one; rule is a JSON object or grep-compatible YAML rule string) — pattern must match the COMPLETE node, so include the parts the real node has: a fn WITH a return type only matches if the pattern has one too (`function $N($$$A): $R { $$$B }`); omitting it returns 0. Shapes: `function $N($$$A) { $$$B }` (no-return-type fn), `($$$A) => $$$B` (arrow, block+expression), `$F($$$A)` (call), `$O.$M($$$A)` (method). For \"find symbol X\" the ROBUST form is a rule, not a pattern: `{ kind:\"function_declaration\", has:{ pattern:\"X\" } }`. 0 matches + no parse error = pattern shape ≠ real node (add `: $R`, or switch to a rule). Note: $$$-only patterns skip files with no literal anchor → low counts; add a literal name or use a regex where.";
-        readonly field: "{ kind:\"field\", field:\"path\"|\"basename\"|\"extension\"|\"size\"|\"modified\"|\"accessed\"|\"empty\"|\"permissions\"|\"executable\"|\"readable\"|\"writable\"|\"entryType\", op:\"=\"|\"!=\"|\"in\"|\"exists\"|\"glob\"|\"regex\"|\">\"|\">=\"|\"<\"|\"<=\"|\"within\"|\"before\", value? } (use symbolic ops like \"=\"; aliases such as \"eq\" are invalid; there is no \"contains\" op — use op:\"glob\", value:\"*term*\" or op:\"regex\"; \"within\"/\"before\" compare modified/accessed times; empty/executable/readable/writable are boolean file attributes paired with op:\"exists\" or op:\"=\") SCOPE: field predicates evaluate file attributes, so they run on target:\"files\" (and mixed into files-lane booleans); target:\"code\" rejects a bare field predicate with unsupportedPredicate — use text/regex/structural for code content, or target:\"files\" for file discovery.";
-        readonly boolean: "{ kind:\"all\"|\"any\", of: Predicate[] } | { kind:\"not\", predicate }";
-        readonly booleanSugar: "Top-level sugar keys lower to canonical booleans at normalize time: and:[...]→all, or:[...]→any, noneOf:[...]→not(any), xor:[a,b]→any(all(a,not b),all(not a,b)), oneOf:[...]→exactly-one expansion (bounded by controls.budget.maxBooleanExpansion), invert:true→not(where). Prefer canonical all/any/not in programmatic queries; sugar is for terse hand-written ones.";
-    };
-    readonly batch: {
-        readonly queries: "OqlQuery[] (1-5)";
-        readonly combine: "independent | merge";
-    };
-    readonly explainRoutes: {
-        readonly PUSHDOWN: "Backend evaluates this predicate exactly — good. No residual work.";
-        readonly RESIDUAL: "Backend narrows candidates but OQL must finish evaluation locally.";
-        readonly ROUTE: "OQL must use a different lane, often materialization.";
-        readonly UNSUPPORTED: "OQL cannot execute this predicate safely on the chosen source.";
-    };
-    readonly defaults: {
-        schema: "oql";
-        view: "paginated";
-        page: number;
-        itemsPerPage: number;
-        githubMaterializeMode: "never";
-        textCase: "smart";
-        regexDialectLocal: "rust";
-        regexCase: "smart";
-        contentView: "standard";
-        contentCharLength: number;
-        matchContentLength: number;
-        maxPlanNodes: number;
-        maxBooleanExpansion: number;
-        normalCodeContext: number;
-        detailedCodeContext: number;
-        localSearchSort: "relevance";
-        localRankingProfile: "auto";
-    };
-};
-export declare function oqlSchemaText(): string;
-export declare function oqlCompactSchemeJson(): string;
-/**
- * Lean, agent-facing summary of the OQL contract, served by
- * `octocode search --scheme --compact`. Every section is DERIVED from
- * `OQL_SCHEMA_DOC` (sourceGuide, targetDecisionTree, quickStart, semanticsGuide,
- * agentBestPractices, evidenceSemantics) so it can never drift from the full
- * `--scheme`. Cold agents read this; advanced flows stay in the full schema.
- */
-export declare function oqlCompactSchemeText(): string;

package/dist/oql/shorthand/predicates.d.ts

@@ -1,15 +0,0 @@
-/**
- * `where` predicate lowering for `octocode search`.
- *
- * Turns the flat shorthand flags (--pattern/--rule/--regex/text, plus the
- * file-discovery field flags like --extension/--filename/--size-greater)
- * into the canonical `Predicate` tree. Predicate precedence within a search
- * term is pattern > rule > regex > text.
- */
-import type { Predicate } from '../types.js';
-import type { SearchShorthand } from './types.js';
-export declare function buildPredicate(parts: SearchShorthand): {
-    where?: Predicate;
-} | {
-    error: string;
-};

package/dist/oql/shorthand/query-controls.d.ts

@@ -1,18 +0,0 @@
-/**
- * `controls`/`fetch`/`materialize`/`view` lowering for `octocode search`.
- *
- * These are the non-predicate parts of an OQL query: search-result shaping
- * (counting, dedup, context, ranking), content/tree fetch instructions, the
- * materialize policy, and the discovery/paginated/detailed view mode.
- */
-import type { OqlInputQuery, QueryControls, QueryView } from '../types.js';
-import type { SearchShorthand } from './types.js';
-export declare function queryControls(parts: SearchShorthand): QueryControls | undefined;
-export declare function fetchInstructions(parts: SearchShorthand): OqlInputQuery['fetch'] | undefined;
-export declare function materializePolicy(parts: SearchShorthand): OqlInputQuery['materialize'] | undefined;
-export declare function resolveView(value: string | undefined): {
-    view?: QueryView;
-} | {
-    error: string;
-};
-export declare function hasContentFetch(parts: SearchShorthand): boolean;

package/dist/oql/shorthand/target-params.d.ts

@@ -1,9 +0,0 @@
-/**
- * `params` lowering for `octocode search` — target-specific parameter bags.
- *
- * Every active target (semantics, repositories, packages, pullRequests,
- * commits, diff, research/graph) accepts its own flat `params`
- * shape; this maps the shared shorthand flags onto each target's fields.
- */
-import type { SearchShorthand } from './types.js';
-export declare function targetParams(parts: SearchShorthand): Record<string, unknown>;

package/dist/oql/shorthand/types.d.ts

@@ -1,159 +0,0 @@
-/**
- * Public shorthand input types for `octocode search`.
- *
- * `SearchShorthand` is the flat, CLI-flag-shaped bag of parts the shorthand
- * lowering pipeline (see ../shorthand.ts) consumes; `ShorthandResult` is what
- * it produces (either a lowered OQL input or a typed error).
- */
-import type { OqlInputBatch, OqlInputQuery } from '../types.js';
-/** Corpus already classified by the caller (local path vs GitHub ref). */
-export type ShorthandCorpus = {
-    kind: 'local';
-    path: string;
-} | {
-    kind: 'github';
-    repo: string;
-    path?: string;
-    ref?: string;
-} | {
-    kind: 'npm';
-};
-export interface SearchShorthand {
-    target?: string;
-    view?: string;
-    contentView?: string;
-    search?: string;
-    /** literal text term (used when no pattern/rule/regex flag is set) */
-    text?: string;
-    /** regex pattern (rust dialect unless pcre2) */
-    regex?: string;
-    pcre2?: boolean;
-    /** structural AST pattern (requires lang) */
-    pattern?: string;
-    /** structural rule, already parsed from JSON (requires lang) */
-    rule?: unknown;
-    lang?: string;
-    corpus: ShorthandCorpus;
-    materialize?: 'never' | 'auto' | 'required';
-    branch?: string;
-    forceRefresh?: boolean;
-    limit?: number;
-    page?: number;
-    itemsPerPage?: number;
-    include?: string[];
-    exclude?: string[];
-    excludeDir?: string[];
-    extension?: string;
-    filename?: string;
-    pathPattern?: string;
-    hidden?: boolean;
-    noIgnore?: boolean;
-    minDepth?: number;
-    maxDepth?: number;
-    empty?: boolean;
-    modifiedWithin?: string;
-    modifiedBefore?: string;
-    accessedWithin?: string;
-    sizeGreater?: string;
-    sizeLess?: string;
-    permissions?: string;
-    executable?: boolean;
-    readable?: boolean;
-    writable?: boolean;
-    details?: boolean;
-    showModified?: boolean;
-    caseInsensitive?: boolean;
-    caseSensitive?: boolean;
-    wholeWord?: boolean;
-    fixedString?: boolean;
-    multiline?: boolean;
-    multilineDotall?: boolean;
-    filesOnly?: boolean;
-    directoriesOnly?: boolean;
-    filesWithoutMatch?: boolean;
-    entryType?: 'file' | 'directory';
-    countLinesPerFile?: boolean;
-    countMatchesPerFile?: boolean;
-    onlyMatching?: boolean;
-    unique?: boolean;
-    countUnique?: boolean;
-    contextLines?: number;
-    invertMatch?: boolean;
-    matchWindow?: number;
-    matchContentLength?: number;
-    maxMatchesPerFile?: number;
-    matchPage?: number;
-    maxFiles?: number;
-    sort?: string;
-    sortReverse?: boolean;
-    rankingProfile?: string;
-    debugRanking?: boolean;
-    matchString?: string;
-    matchRegex?: boolean;
-    matchCaseSensitive?: boolean;
-    startLine?: number;
-    endLine?: number;
-    charOffset?: number;
-    charLength?: number;
-    fullContent?: boolean;
-    tree?: boolean;
-    includeSizes?: boolean;
-    op?: string;
-    symbol?: string;
-    symbolKind?: string;
-    uri?: string;
-    line?: number;
-    order?: number;
-    orderDirection?: string;
-    depth?: number;
-    workspaceRoot?: string;
-    format?: string;
-    owner?: string;
-    topic?: string[];
-    stars?: string;
-    forks?: string;
-    goodFirstIssues?: string;
-    license?: string;
-    created?: string;
-    updated?: string;
-    closed?: string;
-    mergedAt?: string;
-    size?: string;
-    match?: string[];
-    archived?: boolean;
-    visibility?: string;
-    concise?: boolean;
-    state?: string;
-    author?: string;
-    label?: string;
-    prNumber?: number;
-    base?: string;
-    head?: string;
-    draft?: boolean;
-    commentsContent?: boolean;
-    commitsContent?: boolean;
-    deep?: boolean;
-    patchFile?: string;
-    reviewMode?: string;
-    filePage?: number;
-    commentPage?: number;
-    commitPage?: number;
-    since?: string;
-    until?: string;
-    patches?: boolean;
-    baseRef?: string;
-    headRef?: string;
-    diffPath?: string;
-    intent?: string;
-    facets?: string[];
-    proof?: string;
-    proofLimit?: number;
-    includePackets?: boolean;
-    includeFacts?: boolean;
-    includeEdges?: boolean;
-}
-export type ShorthandResult = {
-    input: OqlInputQuery | OqlInputBatch;
-} | {
-    error: string;
-};

package/dist/oql/shorthand/utils.d.ts

@@ -1,7 +0,0 @@
-/**
- * Small stateless helpers shared across the shorthand lowering builders.
- */
-/** Drop `undefined` values so callers don't emit sparse-but-present keys. */
-export declare function clean(input: Record<string, unknown>): Record<string, unknown>;
-export declare function listFromComma(value: string): string[];
-export declare function isTreeSort(value: string | undefined): value is 'name' | 'size' | 'time' | 'extension';

package/dist/oql/shorthand.d.ts

@@ -1,8 +0,0 @@
-import type { SearchShorthand, ShorthandCorpus, ShorthandResult } from './shorthand/types.js';
-export type { SearchShorthand, ShorthandCorpus, ShorthandResult };
-/**
- * Lower shorthand parts into the OQL sugar object. Predicate precedence:
- * pattern > rule > regex > text. Returns a typed error for invalid combos
- * (e.g. structural without `lang`) instead of throwing.
- */
-export declare function buildShorthandInput(parts: SearchShorthand): ShorthandResult;

package/dist/oql/targetParams.d.ts

@@ -1,7 +0,0 @@
-import type { OqlActiveTarget } from './types.js';
-/**
- * Validate a target's `params` bag against its typed schema. Returns `null` when
- * valid (or no schema applies), or a Zod-style error message string the caller
- * raises as `invalidQuery`.
- */
-export declare function validateTargetParams(target: OqlActiveTarget, params: unknown): string | null;

package/dist/oql/transformers/contract.d.ts

@@ -1,19 +0,0 @@
-import type { OqlActiveTarget, OqlRecordResultRow, QuerySource } from '../types.js';
-export type TransformerStatus = 'active' | 'planned';
-export type TransformerBackend = {
-    readonly backend: string;
-    readonly operation: string;
-    readonly exact: boolean;
-};
-export type TransformerRegistryEntry = {
-    readonly id: string;
-    readonly target: OqlActiveTarget;
-    readonly sourceKinds: readonly QuerySource['kind'][];
-    readonly status: TransformerStatus;
-    readonly backends: readonly TransformerBackend[];
-    readonly rowKind: 'code' | 'file' | 'tree' | 'content' | 'record';
-    readonly recordType?: OqlRecordResultRow['recordType'];
-    readonly adapterModule?: string;
-    readonly adapterFunctions: readonly string[];
-    readonly notes?: readonly string[];
-};

package/dist/oql/transformers/github/code.d.ts

@@ -1,9 +0,0 @@
-import type { OqlQuery } from '../../types.js';
-import type { TransformResult } from '../types.js';
-export type GithubCodeSearchToolQuery = Record<string, unknown>;
-export type GithubCodeSearchTransformOptions = {
-    defaultMatch?: 'file' | 'path';
-    unsupportedMessage?: string;
-    unsupportedBackend?: string;
-};
-export declare function toGithubCodeSearchToolQuery(query: OqlQuery, options?: GithubCodeSearchTransformOptions): TransformResult<GithubCodeSearchToolQuery>;

package/dist/oql/transformers/github/common.d.ts

@@ -1,14 +0,0 @@
-import type { OqlQuery, Predicate, QueryScope, QuerySource } from '../../types.js';
-/**
- * Collect the leaf predicates (text/regex/structural/field) of a `where`
- * tree. Mirrors the planner's walk without importing planner.ts (cycle risk);
- * used to verify a provider transformer consumed every routed leaf.
- */
-export declare function leafPredicates(where: Predicate): Predicate[];
-export declare function splitGithubSource(source: QuerySource | undefined): {
-    owner?: string;
-    repo?: string;
-};
-export declare function firstScopePath(scope: QueryScope | undefined): string | undefined;
-export declare function firstScopeLanguage(scope: QueryScope | undefined): string | undefined;
-export declare function requestedRowLimit(query: OqlQuery): number | undefined;

package/dist/oql/transformers/language.d.ts

@@ -1 +0,0 @@
-export { classifyLanguageSelector, toGithubCodeLanguageParams, toGithubRepositoryLanguage, toLocalFileLanguageGlobs, toLocalSearchLanguageParams, } from '../../shared/languageSelectors.js';

package/dist/oql/transformers/registry.d.ts

@@ -1,16 +0,0 @@
-import type { OqlActiveTarget, OqlBackendCall, OqlTransformerTrace, QuerySource } from '../types.js';
-import type { TransformerRegistryEntry } from './contract.js';
-export declare function listTransformerEntries(): readonly TransformerRegistryEntry[];
-export declare function findTransformerEntry(args: {
-    sourceKind: QuerySource['kind'];
-    target: OqlActiveTarget;
-    variant?: string;
-}): TransformerRegistryEntry | undefined;
-export declare function findTransformerById(id: string): TransformerRegistryEntry | undefined;
-export declare function findTransformerForQuery(args: {
-    source?: QuerySource;
-    target: OqlActiveTarget;
-    params?: Record<string, unknown>;
-}): TransformerRegistryEntry | undefined;
-export declare function backendCallsForTransformer(entry: TransformerRegistryEntry, source?: QuerySource): OqlBackendCall[];
-export declare function transformerTrace(entry: TransformerRegistryEntry): OqlTransformerTrace;

package/dist/oql/transformers/types.d.ts

@@ -1,11 +0,0 @@
-import type { OqlDiagnostic } from '../types.js';
-export type TransformOk<TQuery extends Record<string, unknown>> = {
-    ok: true;
-    query: TQuery;
-    diagnostics: OqlDiagnostic[];
-};
-export type TransformBlocked = {
-    ok: false;
-    diagnostics: OqlDiagnostic[];
-};
-export type TransformResult<TQuery extends Record<string, unknown>> = TransformOk<TQuery> | TransformBlocked;

package/dist/oql/types/diagnostics.d.ts

@@ -1,22 +0,0 @@
-/**
- * OQL diagnostics — the coded, severity-ranked notices the planner/runner
- * attach to a result envelope (unsupported predicates, truncation, auth,
- * etc.), each optionally carrying a repair suggestion or continuation.
- */
-import type { OqlSearchInput } from './query.js';
-import type { OqlContinuation } from './envelope.js';
-export type DiagnosticCode = 'invalidQuery' | 'ambiguousSugar' | 'unknownField' | 'unsupportedTarget' | 'unsupportedPredicate' | 'unsupportedBoolean' | 'unsupportedScope' | 'negativeUniverseRequired' | 'residualNotExact' | 'fieldTypeMismatch' | 'requiresMaterialization' | 'vendorNoEquivalent' | 'lossyTransform' | 'unsupportedVendorPredicate' | 'responseShapeMismatch' | 'materializationNotAllowed' | 'materializationFailed' | 'providerUnindexed' | 'providerSemanticsApproximate' | 'partialResult' | 'contentTruncated' | 'matchTruncated' | 'planTruncated' | 'budgetExhausted' | 'parserFailed' | 'partialParse' | 'signatureUnsupported' | 'lspUnavailable' | 'staleCache' | 'sanitized' | 'rateLimited' | 'authRequired' | 'zeroMatches' | 'symbolNotFound';
-export interface OqlDiagnostic {
-    code: DiagnosticCode;
-    severity: 'info' | 'warning' | 'error';
-    queryPath?: string;
-    predicateId?: string;
-    backend?: string;
-    message: string;
-    blocksAnswer: boolean;
-    repair?: {
-        message: string;
-        suggestedQuery?: OqlSearchInput;
-    };
-    continuation?: OqlContinuation;
-}

package/dist/oql/types/envelope.d.ts

@@ -1,78 +0,0 @@
-/**
- * OQL result envelope — pagination, provenance, continuations, and the
- * top-level `OqlResultEnvelope`/`OqlBatchResultEnvelope` shapes `runOqlSearch`
- * returns.
- */
-import type { QuerySource } from './predicates.js';
-import type { OqlCanonicalInput } from './query.js';
-import type { OqlDiagnostic } from './diagnostics.js';
-import type { OqlExplainPlan } from './planner.js';
-import type { OqlProofGradedResultRow } from './recordRows.js';
-export interface Pagination {
-    currentPage?: number;
-    totalPages?: number;
-    nextPage?: number;
-    itemsPerPage?: number;
-    totalItems?: number;
-    reportedTotalItems?: number;
-    reachableTotalItems?: number;
-    totalItemsKind?: string;
-    itemUnit?: string;
-    rowCount?: number;
-    reportedRowCount?: number;
-    totalItemsCapped?: boolean;
-    uniqueFileCount?: number;
-    hasMore: boolean;
-    next?: OqlContinuation;
-}
-export interface OqlProvenance {
-    backend: string;
-    source?: QuerySource;
-    predicateIds?: string[];
-    pushed?: string[];
-    residual?: string[];
-    routed?: string[];
-    materializedPath?: string;
-    cache?: 'hit' | 'miss' | 'refresh' | 'stale';
-}
-export interface OqlContinuation {
-    query: OqlCanonicalInput;
-    baseQueryId?: string;
-    queryIndex?: number;
-    why?: string;
-    confidence?: 'exact' | 'heuristic';
-}
-export interface OqlContinuationHint {
-    why: string;
-    confidence: 'exact' | 'heuristic';
-}
-export type EvidenceKind = 'proof' | 'partial' | 'candidate' | 'unsupported';
-export interface OqlResultEnvelope {
-    queryId?: string;
-    queryIndex?: number;
-    results: OqlProofGradedResultRow[];
-    shared?: Record<string, unknown>;
-    pagination?: Pagination;
-    next?: Record<string, OqlContinuation>;
-    nextHints?: Record<string, OqlContinuationHint>;
-    diagnostics: OqlDiagnostic[];
-    provenance: OqlProvenance[];
-    evidence: {
-        answerReady: boolean;
-        complete: boolean;
-        kind: EvidenceKind;
-    };
-    plan?: OqlExplainPlan;
-}
-export interface OqlBatchResultEnvelope {
-    batchId?: string;
-    mode: 'independent' | 'merge';
-    children: Array<{
-        queryId: string;
-        queryIndex: number;
-        envelope: OqlResultEnvelope;
-    }>;
-    merged?: OqlResultEnvelope;
-    diagnostics: OqlDiagnostic[];
-}
-export type OqlRunResult = OqlResultEnvelope | OqlBatchResultEnvelope;

package/dist/oql/types/guards.d.ts

@@ -1,9 +0,0 @@
-/**
- * OQL type guards — runtime discriminators for the input/output union types
- * (single query vs batch, single envelope vs batch envelope).
- */
-import type { OqlBatch, OqlCanonicalInput, OqlInputBatch, OqlSearchInput } from './query.js';
-import type { OqlBatchResultEnvelope, OqlRunResult } from './envelope.js';
-export declare function isBatchInput(input: OqlSearchInput): input is OqlInputBatch;
-export declare function isCanonicalBatch(input: OqlCanonicalInput): input is OqlBatch;
-export declare function isBatchEnvelope(result: OqlRunResult): result is OqlBatchResultEnvelope;

package/dist/oql/types/planner.d.ts

@@ -1,46 +0,0 @@
-/**
- * OQL planner — the explain-plan shapes describing how a query's predicates
- * were routed to backends (pushdown/residual/route/unsupported), the backend
- * calls made, and transformer traces, surfaced when `explain:true`.
- */
-import type { PredicateId, QuerySource } from './predicates.js';
-import type { MaterializePolicy, OqlCanonicalInput, QueryControls } from './query.js';
-import type { OqlDiagnostic } from './diagnostics.js';
-import type { OqlContinuation } from './envelope.js';
-export type PlanRoute = 'PUSHDOWN' | 'RESIDUAL' | 'ROUTE' | 'UNSUPPORTED';
-export interface OqlPlanNode {
-    predicateId: PredicateId;
-    path: string;
-    route: PlanRoute;
-    backend?: string;
-    reason: string;
-}
-export interface OqlBackendCall {
-    backend: string;
-    source?: QuerySource;
-    operation: string;
-    exact: boolean;
-}
-export interface OqlTransformerTrace {
-    id: string;
-    status: string;
-    sourceKinds: readonly string[];
-    target: string;
-    backends: readonly Pick<OqlBackendCall, 'backend' | 'operation' | 'exact'>[];
-}
-export interface OqlExplainPlan {
-    input: unknown;
-    normalized: OqlCanonicalInput;
-    defaults: Record<string, unknown>;
-    nodes: OqlPlanNode[];
-    backendCalls: OqlBackendCall[];
-    transformers?: readonly OqlTransformerTrace[];
-    materialization?: MaterializePolicy & {
-        required: boolean;
-        reason: string;
-    };
-    budgets: QueryControls['budget'];
-    truncated?: boolean;
-    diagnostics: OqlDiagnostic[];
-    next?: Record<string, OqlContinuation>;
-}